The right way: Local editor
Contents
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.
Workflow#
GitHub setup#
We assume that you have set up a GitHub account with working public keys.
See: Basic SSH config.
See: Key pair creation.
Install Docker#
Before you start, make sure that you have installed Docker.
Install the Duckietown Shell#
Install the Duckietown Shell using these instructions.
Fork the 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 src/
.
Images are stored in the directory src/_images
, while CSS
and JS
files can be dropped inside the
directory src/_static
and will be automatically loaded.
Compile HTML#
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 html/
.
Open the file html/index.html
to start. Make sure that your changes look the way you want them to.
Compile PDF#
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 pdf/
.
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.
Attention
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]
where [DNS]
is the hostname of the documentation website to push the artifacts to,
e.g., docs.duckietown.com
.
Note
This is only allowed on staging servers, e.g., staging-docs.duckietown.com
. Only Jenkins can publish
to production.