https://github.com/buildthedocs/btd

A multi-version Sphinx building tool based on containers
https://github.com/buildthedocs/btd

container docker documentation sphinx static-site-generation

Last synced: 5 months ago
JSON representation

A multi-version Sphinx building tool based on containers

• Host: GitHub
• URL: https://github.com/buildthedocs/btd
• Owner: buildthedocs
• License: apache-2.0
• Created: 2017-12-26T23:06:33.000Z (over 8 years ago)
• Default Branch: main
• Last Pushed: 2026-01-02T01:01:28.000Z (6 months ago)
• Last Synced: 2026-01-07T14:42:01.380Z (6 months ago)
• Topics: container, docker, documentation, sphinx, static-site-generation
• Language: Shell
• Homepage: https://buildthedocs.github.io/btd/
• Size: 3.07 MB
• Stars: 13
• Watchers: 1
• Forks: 2
• Open Issues: 7
• Metadata Files:
  • Readme: README.md
  • Contributing: .github/CONTRIBUTING.md
  • License: LICENSE

Awesome Lists containing this project

README

          


  

  

  

  

  



# Build The Docs (BTD)

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](http://www.sphinx-doc.org).

- 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](https://github.com).

- Web site hosted on [GitHub Pages](https://pages.github.com/).

- 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`.

# Usage

This project is available as a Python package ([btd](btd)), along with the plumbing to use it as a GitHub Action.

Find usage guidelines and examples at [buildthedocs.github.io/btd](https://buildthedocs.github.io/btd).