The right way: Local editor
The right way: Local editor#
This section describes the workflow to edit the documentation for one single book.
In a nutshell:
You fork the repos to your GitHub account.
You compile locally using a Docker container (no installation necessary).
You contribute by opening a pull request.
We assume that you have set up a GitHub account with working public keys.
See: Basic SSH config.
See: Key pair creation.
Before you start, make sure that you have installed Docker.
Install the Duckietown Shell#
Install the Duckietown Shell using these instructions.
book-[name] repository on GitHub#
Navigate to the book repository page on GitHub, and click on the Fork button at the top-right corner of the page.
This will create a new repository on your account that is linked to the original one.
Checkout your fork locally#
Check out the forked repository locally.
Do your edits#
Do your edits on your local copy of the repository.
The source files are in the directory
Images are stored in the directory
JS files can be dropped inside the
src/_static and will be automatically loaded.
Compile using the
dts docs commands in the Duckietown Shell:
dts docs build
Clean up artifacts and build cache with the command,
dts docs clean
View the HTML#
Once built, the book will be exported as HTML inside the directory
Open the file
html/index.html to start. Make sure that your changes look the way you want them to.
Compile the book into a PDF file using the command,
dts docs build --pdf
View the PDF#
Once built, the book will be exported as PDF inside the directory
Open the file
pdf/book.pdf to start. Make sure that your changes look the way you want them to.
Commit and push#
Commit and push as you would do normally.
You need to be part of the
Developers - Docs
team on GitHub to be able to push changes to the documentation repositories. Ask your supervisor if you
don’t have access.
Make a pull request#
Create a pull request to the original repository.
Publish artifacts directly#
While it is recommended to use Continuous Integration (CI) systems (e.g., Jenkins, CircleCI) to perform automatic builds and deployments of the documentation, you can decide to push your local artifacts to the corresponding HTTP server. You can do so by running the following command,
dts docs publish [DNS]
[DNS] is the hostname of the documentation website to push the artifacts to,
This is only allowed on staging servers, e.g.,
staging-docs.duckietown.com. Only Jenkins can publish