Quickdocs

Creates HTML docs from a project's readme and sphinx-apidoc.

Status

Source	Shields
Project
Health
Repository
Publishers
Activity

Installation

pip install quickdocs

Usage

To create an up to date sphinx configuration:

quickdocs .quickdocs.yml

Now we can build the documentation:

sphinx-build -E docs build

This will run copy and markup the project's readme at runtime so that you don't need to recompile the sphinx configuration unless any of the settings change.

Required settings file fields:

project: Quickdocs
version: 1.2.1
author: Joel Lefkowitz
html_title: Quickdocs
github_url: JoelLefkowitz/quickdocs

Optional settings:

debug: # Default: False
project_root: # Default: os.getcwd()
verbose_name: # Default: None

markup_readme: # Default: True
readme_path: # Default: "README.md"

apidoc_module_dir: # Default: None

Integrating with readthedocs

.readthedocs.yml:

version: 2

sphinx:
  configuration: docs/conf.py

formats: all

python:
  version: 3.8
  install:
    - requirements: docs/requirements.txt

Removing old documentation

The sphinx-apidoc plugin generates documentation under docs/api. When running, the sphinx plugin will overwrite but not delete out of date files in this directory. This means if you rename a module you must delete the out of date documentation. This package should not delete the docs/api directory because some developers will add custom documentation to this directory as they write new modules.

Tests

To run unit tests and generate a coverage report:

grunt tests:unit

Documentation

This repository's documentation is hosted on readthedocs.

To generate the sphinx configuration:

grunt docs:generate

Then build the documentation:

grunt docs:build

Tooling

To run linters:

grunt lint

To run formatters:

grunt format

Before committing new code:

grunt precommit

This will run linters, formatters, tests, generate a test coverage report and the sphinx configuration.

Continuous integration

This repository uses Travis CI to build and test each commit. Formatting tasks and writing documentation must be done before committing new code.

Versioning

This repository adheres to semantic versioning standards. For more information on semantic versioning visit SemVer.

Bump2version is used to version and tag changes. For example:

bump2version patch

Changelog

Please read this repository's CHANGELOG for details on changes that have been made.

Contributing

Please read this repository's guidelines on CONTRIBUTING for details on our code of conduct and the process for submitting pull requests.

Contributors

• Joel Lefkowitz - Initial work - Joel Lefkowitz

Remarks

Lots of love to the open source community!