A command-line tool for building documentation from repositories into HTML files. Initially based on https://github.com/juju/docs/blob/master/tools/mdbuild.py.
Project description
Archived
This project is legacy and should not be used for new documentation. Existing documentation projects using it should be migrated to the Discourse model, or use another solution. If you manage such a project, please reach out to us to facilitate the upgrade.
Ubuntu documentation builder
Maintenance mode
documentation-builder is now considered a legacy product, as all user maintained documentation sets should now be moving to the discourse-docs model.
Important fixes will still be performed, but we will not be adding new features.
A tool for building a set of documentation files in HTML format, from a remote git repository containing markdown files.
Installation
The best way to install documentation-builder is with snap:
sudo snap install documentation-builderIf you don’t have snap on your system, you can also install it with pip3:
pip3 install ubuntudesign.documentation-builderFor more information see the documentation.
Development
documentation-builder is a Python module. The main application code lives in ubuntudesign/documentation_builder. Updates to the markup or styling should be made in the default template.
Checking changes
To check your changes to documentation-builder, it’s probably easiest to install the module locally, in editable mode, within an encapsulated environment:
python3 -m venv env3 && source env3/bin/activate # Create encapsulated environment
pip install -e . # Install the module in editable mode
documentation-builder --source-folder docs # build the documentation-builder's own documentation
xdg-open build/en/index.html # Open up the documentation pageWatching for changes
On Ubuntu et al. you can use inotifywait to watch for changes to the source files, and rebuild when something changes as follows:
sudo apt install inotify-tools # Ensure inotifywait is installed
# Force rebuild docs when anything changes in the source folder
while inotifywait -r -e close_write "./ubuntudesign"; do bin/documentation-builder --force --source-folder docs; doneTests
To run tests:
./setup.py testDebugging
To run a specific test:
./setup.py test --addopts tests/test_operations.py::test_find_filesYou can debug tests by adding a debugger to the code and running the test again.
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
File details
Details for the file ubuntudesign.documentation-builder-1.6.5.tar.gz.
File metadata
- Download URL: ubuntudesign.documentation-builder-1.6.5.tar.gz
- Upload date:
- Size: 51.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.2.0 pkginfo/1.4.2 requests/2.23.0 setuptools/49.3.1 requests-toolbelt/0.8.0 tqdm/4.48.2 CPython/3.8.10
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 6b2fb576a535b58fd5bc058e7208014c068897b2f9e35a0e24cced99b26573e0 |
|
| MD5 | be7c1a9f422b263813ad1b72a8db963b |
|
| BLAKE2b-256 | 72b993afdd91c8c6e2dd6cd4f65a031e759ce74a8652705cca7f5d14a615e88b |
