build details

Show: section status errors & todos local changes recent changes last change in-page changes feedback controls

Second method: local editing+docker

✎

Modified 2018-08-27 by Andrea Censi

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

✎

Modified 2018-06-24 by Andrea Censi

Github setup

✎

Modified 2019-04-15 by tanij

We assume that you have setup a Github account with working public keys.

Basic SSH config (unknown ref software_reference/github-access)

warning next (1 of 17) index
warning
I will ignore this because it is an external link. 

 > I do not know what is indicated by the link '#software_reference/github-access'.

Location not known more precisely.

Created by function n/a in module n/a.
.

Key pair creation (unknown ref software_reference/howto-create-key-pair)

previous warning next (2 of 17) index
warning
I will ignore this because it is an external link. 

 > I do not know what is indicated by the link '#software_reference/howto-create-key-pair'.

Location not known more precisely.

Created by function n/a in module n/a.
.

Adding public key on Github (unknown ref software_reference/github-access)

previous warning next (3 of 17) index
warning
I will ignore this because it is an external link. 

 > I do not know what is indicated by the link '#software_reference/github-access'.

Location not known more precisely.

Created by function n/a in module n/a.
.

Install Docker

✎

Modified 2018-06-24 by Andrea Censi

Before you start, make sure that you have installed Docker (unknown ref software_reference/docker)

previous warning next (4 of 17) index
warning
I will ignore this because it is an external link. 

 > I do not know what is indicated by the link '#software_reference/docker'.

Location not known more precisely.

Created by function n/a in module n/a.
.

Install the Duckieton Shell

✎

Modified 2019-04-15 by tanij

Install the Duckietown Shell using these instructions.

Fork the docs-book repo on the Github site

✎

Fork one of the docs-book repos on the Github site (Figure 3.1).

This will create a new repo on your account that is linked to the original one.

Checkout your fork locally

✎

Modified 2018-06-24 by Andrea Censi

Check out the forked repository as you would do normally.

Initialize your folder

✎

Modified 2019-04-15 by tanij

Go into the folder:

$ cd docs-book

When compiling a book for the first time, you need to run:

$ git submodule init

And:

$ git submodule update

Do your edits

✎

Modified 2019-12-27 by nikihowe

Do your edits on your local copy. The source files are in the directory book/book. The file and folder names start with numbers, these are used to determine the order that things show up in output.

Compile

✎

Modified 2019-04-15 by tanij

Compile using the docs commands in the Duckietown Shell:

$ dts docs build

Re-compile from scratch using:

$ dts docs clean
$ dts docs build

If there are errors you should open duckuments-dist/errors.html and look at them and fix them.

Look at the local copy

✎

Modified 2019-04-15 by tanij

Open the file index.html and navigate to whichever pages you have changed to make sure that they look the way want them to.

Commit and push

✎

Modified 2018-06-24 by Andrea Censi

Commit and push as you would do normally.

Make a pull request

✎

Modified 2018-06-24 by Andrea Censi

Create a pull request to the original repository.

Option 1: Use the Github website

✎

Github offers a nice interface to create a pull request.

TODO for volunteer: add image of pull request

task next (1 of 11) index
for:volunteertask

The following was marked as "todo".

TODO for volunteer: add image of pull request

Location not known more precisely.

Created by function n/a in module n/a.

Option 2: Use the command-line program hub

✎

You can create a pull request from the command-line using hub (unknown ref software_reference/hub)

previous warning next (5 of 17) index
warning
I will ignore this because it is an external link. 

 > I do not know what is indicated by the link '#software_reference/hub'.

Location not known more precisely.

Created by function n/a in module n/a.
:

$ hub pull-request

(unknown ref software_reference/hub)

previous warning next (6 of 17) index
warning
I will ignore this because it is an external link. 

 > I do not know what is indicated by the link '#software_reference/hub'.

Location not known more precisely.

Created by function n/a in module n/a.

Using CircleCI

✎

Modified 2018-09-22 by Andrea Censi

Circle CI makes it easier to check whether there are problems to be fixed.

Sign up on Circle

✎

Modified 2018-06-24 by Andrea Censi

Sign up on the Circle CI service, at the link circleci.com.

Activate your build on Circle

✎

Modified 2018-08-05 by Andrea Censi

Activate the building at the link:

https://circleci.com/setup-project/gh/username/duckuments

where username is your Github username.

Click β€œstart building”.

Make sure everything compiles on Circle

✎

Go to the URL:

https://circleci.com/gh/username/duckuments

to see the status of your build.

You can also preview the results by clicking the β€œartifacts” tab and selecting index.html from the list.