This is a proof-of-concept to provide a 'lightweight' multi-version documentation generator for users that:
- Rely on a git hosting service to handle users and access permissions.
- Need to generate/build documentation in different formats (HTML, PDF, EPUB...) and for multiple versions of a project, using Sphinx.
- Want to be able to generate/build the documentation and have the products optionally deployed to a hosting service automatically.
The most expected use case is:
- Project hosted on GitHub.
- Web site hosted on GitHub Pages.
- A GitHub Actions workflow to build the site after each push.
Possible schemes:
- Save doc sources in:
- A subdir of master/development branches.
- TODO: The root of a given branch.
- Deploy to, either the same or a different repository:
- Branch
master. - Branch
gh-pages. - TODO: Subdir docs in branch
master.
- Branch
This project is available as a Python package (btd), along with the plumbing to use it as a GitHub Action. Find usage guidelines and examples at buildthedocs.github.io/btd.
This project (BTD) started as an alternative to readthedocs.org (RTD.org) for users that don't need most of the features that RTD.org provides as a service (webhooks, user/team/project management, web frontend or API to modify settings, etc), because they use a different web hosting service and a CI service, such as, GitHub Pages and GitHub Actions. See rtfd/readthedocs-build#35.
There is a Python package with the same name as this project: pietroalbini/buildthedocs. The development of both projects is independent ATM, but the same name is used because both tools are meant for the same exact usage. Differences are found in implementation details:
- The Python package is expected to be executed natively or inside a VM/container which has all the required dependencies pre-installed.
- This project is expected to be executed either natively or in CI jobs with docker. Multiple docker images with pre-installed dependencies are used to provide ready-to-use environments for each task.