Creates HTML docs from a project's readme and sphinx-apidoc
Project description
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.0
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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for quickdocs-1.2.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9578f524dcffacbd69559a08c01ef54c73b9e2eca0a82c5942287cb9dd5fc55c |
|
MD5 | 9a016ce337e943b54c16be36f3860d01 |
|
BLAKE2b-256 | 7936a2cb7ff4a089155ced9971fd262504a1bd113264b42686e3090ecb070650 |