https://github.com/joellefkowitz/quickdocs
Create HTML docs from a project's readme and sphinx-apidoc.
https://github.com/joellefkowitz/quickdocs
apidoc documentation sphinx
Last synced: 4 months ago
JSON representation
Create HTML docs from a project's readme and sphinx-apidoc.
- Host: GitHub
- URL: https://github.com/joellefkowitz/quickdocs
- Owner: JoelLefkowitz
- License: mit
- Created: 2021-02-20T19:34:25.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-05-27T22:09:00.000Z (about 2 years ago)
- Last Synced: 2025-08-03T00:58:05.756Z (11 months ago)
- Topics: apidoc, documentation, sphinx
- Language: Python
- Homepage:
- Size: 173 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Quickdocs
Create HTML docs from a project's readme and sphinx-apidoc.
## Installing
```bash
pip install quickdocs
```
## Documentation
Documentation and more detailed examples are hosted on [Github Pages](https://joellefkowitz.github.io/quickdocs).
## Usage
To create an up to date sphinx configuration:
```bash
quickdocs .quickdocs.yml
```
Now we can build the documentation:
```bash
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:
```yml
project: Quickdocs
version: 1.2.1
author: Joel Lefkowitz
html_title: Quickdocs
github_url: JoelLefkowitz/quickdocs
```
Optional settings:
```yml
debug: # Default: False
project_root: # Default: os.getcwd()
verbose_name: # Default: None
```
```yml
markup_readme: # Default: True
readme_path: # Default: "README.md"
```
```yml
apidoc_module_dir: # Default: None
```
### Integrating with readthedocs
**`.readthedocs.yml`**:
```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.
## Tooling
### Dependencies
To install dependencies:
```bash
yarn install
pip install .[all]
```
### Tests
To run tests:
```bash
thx test
```
### Documentation
To generate the documentation locally:
```bash
thx docs
```
### Linters
To run linters:
```bash
thx lint
```
### Formatters
To run formatters:
```bash
thx format
```
## Contributing
Please read this repository's [Code of Conduct](CODE_OF_CONDUCT.md) which outlines our collaboration standards and the [Changelog](CHANGELOG.md) for details on breaking changes that have been made.
This repository adheres to semantic versioning standards. For more information on semantic versioning visit [SemVer](https://semver.org).
Bump2version is used to version and tag changes. For example:
```bash
bump2version patch
```
### Contributors
- [Joel Lefkowitz](https://github.com/joellefkowitz) - Initial work
## Remarks
Lots of love to the open source community!
