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.

Settings input file:

.quickdocs.yml:

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:
      - method: pip
        path: .
        extra_requirements:
            - docs

Declare the sphinx dependencies:

setup.py:

from setuptools import setup

if __name__ == "__main__":
    setup(
        extras_require={
            "docs": [
                "pypandoc",
                "sphinx",
                "sphinxcontrib.apidoc",
                "sphinxcontrib.pandoc_markdown",
                "sphinx-autodoc-annotation",
                "yummy_sphinx_theme",
            ],
        },
    )

Tests

To run unit tests:

tox

Documentation

Please view our documentation available on readthedocs.

To build locally generate the sphinx configuration:

quickdocs .quickdocs.yml

Then build the documentation:

sphinx-build -E docs build

Tooling

We use grunt to run local tooling before committing code:

Linting

grunt lint

Formatting

grunt format

Documentation and coverage reports should be regenerated before commiting any new code.

Changelog

Please read CHANGELOG.md for details on changes that have been made.

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Versioning

SemVer is used for versioning. For a list of versions available, see the tags on this repository.

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

bump2version patch

Releases are made on every minor change.

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests.

Contributors

• Joel Lefkowitz - Initial work - Joel Lefkowitz