Merge branch 'master' into patch-1

.circleci/config.yml

@@ -2,7 +2,12 @@ version: 2
 jobs:
     build:
         docker:
-        - image: andreacensi/duckuments:master
+        - image: andreacensi/mcdp_books:duckuments@sha256:307d478c8cedaff574e4a94303dae779547a513bd0641e3d4c236a5206b6c77b
+          environment:
+              COLUMNS: 160
+              TERM: xterm-256color
+              EXTRA_MCDP_RENDER_OPTIONS: --ignore_ref_errors
+
         resource_class: large
         steps:
         - checkout
@@ -16,6 +21,27 @@ jobs:
             name: Compile
             command: make compile-native-ci
 
+        - run:
+            name: Link check
+            command: |
+                . /project/deploy/bin/activate && make linkcheck || true
+
+        - run:
+            when: always
+            name: Package artifacts
+            command:  |
+                find duckuments-dist -name '*.old' -delete
+                make package-artifacts
+
+        - store_artifacts:
+              path: out/package.tgz
+              destination: out/package.tgz
+
+
         - store_artifacts:
               path: duckuments-dist
               destination: duckuments-dist
+
+
+        - test-results-store:
+            path: duckuments-dist/junit

.gitignore

@@ -2,3 +2,4 @@ out
 duckuments-dist
 .DS_Store
 node_modules
+.idea

.gitmodules

@@ -1,3 +1,3 @@
 [submodule "resources"]
 	path = resources
-	url = git@github.com:duckietown/docs-resources.git
+	url = https://github.com/duckietown/docs-resources.git

Makefile

@@ -1,11 +1,8 @@
 BASE:=book
-BOOKNAME:=`ls -1 $(BASE)`
+BOOKNAME:=$(shell ls -1 $(BASE) | head -n 1)
 SRC:=book/$(BOOKNAME)
 
-
 all:
 	cat README.md
 
-
-
 include resources/makefiles/setup.Makefile

README.md

@@ -1,16 +1,45 @@
+## Fork this repo
+
+Fork this repo to edit it.
+
+
 ## Running using Docker
-    
+
 First run:
 
     $ git submodule sync --recursive
     $ git submodule update --init --recursive
 
+# Installing Docker
+
 Then install Docker:
 
     $ make install-docker-ubuntu16
 
-You need to logout and login again for ubuntu groups to be updated.
-Then compile using:
 
-    $ make compile-docker
+*Note*: you need to be in group `docker`. The script adds you, but it does not take effect immediately. You will need to exit the console and re-enter. You may need to log out in again for Ubuntu groups to be updated.
+
+*Note*: For Mac OS this is not required.
+
+# Install other dependencies
+
+## Mac OS
+
+    $ brew install coreutils
+
+## Ubuntu
+
+Make sure to have `git 2.13+` and `git lfs 2.5+`. 
+To install the latest versions of these, run the following commands:
+
+1. `sudo add-apt-repository ppa:git-core/ppa && sudo apt update && sudo apt install git`
+2. `curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash`
+3. `sudo apt-get install git-lfs`
+4. `git lfs install`
+5. `git lfs pull` (inside documentation directory)
+
+# Compiling
+
+Then compile using:
 
+    $ make compile-docker

book/duckumentation/10_contributing/10_intro.md

@@ -1,19 +1,19 @@
 # Overview {#duckumentation-intro status=ready} 
 
-TODO: write more about the design principles.
-
 ## Where the documentation is
 
-All the documentation is in the repository `duckietown/duckuments`.
+The documentation is contained in a series of repositories called `docs-![short name]`:
 
-The documentation is written as a series of small files in Markdown format.
+* [docs-duckumentation](http://github.com/duckietown/docs-duckumentation) (this book)
+* [docs-AIDO](http://github.com/duckietown/docs-AIDO) 
+* [docs-software_devel](http://github.com/duckietown/docs-software_devel) 
 
-It is then processed by a series of scripts to create  publication-quality PDF and an online HTML version.
+In addition, there is a repository `duckietown/duckuments` that contains the `docs-![xxx]` repositories as Git submodules.
 
-You can find all these artifacts produced at the site [`docs.duckietown.org`](http://docs.duckietown.org).
+## Documentation format 
 
-## Editing links
+The documentation is written as a series of small files in Markdown format.
 
-The simplest way to contribute to the documentation is to click any of the "✎" icons next to the headers.
+It is then processed by a series of scripts to create publication-quality PDF and an online HTML version.
 
-They link to the "edit" page in Github. There, one can make and commit the edits in only a few seconds.
+You can find all these artifacts produced at the site [`docs.duckietown.org`](http://docs.duckietown.org).

book/duckumentation/10_contributing/40_simple_way.md

@@ -0,0 +1,12 @@
+
+# The simple way to edit the documentation {#duckumentation-contribute-simple status=ready} 
+
+The simplest way to contribute to the documentation is to click any of the "✎" icons next to the headers.
+
+They link to the "edit" page in Github. There, one can make and commit the edits in only a few seconds.
+When committing, please choose "create branch".
+
+
+TODO for volunteer: add screenshot of process
+
+

book/duckumentation/10_contributing/41_workflow.md

@@ -0,0 +1,137 @@
+# Second method: local editing+docker {#duckumentation-workflow status=ready}
+
+This section describes the workflow to edit the documentation for one single obok.
+
+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 setup a Github account with working public keys.
+
+See: [Basic SSH config](+software_reference#ssh-local-configuration).
+
+See: [Key pair creation](+software_reference#howto-create-key-pair).
+
+See: [Adding public key on Github](+software_reference#howto-add-pubkey-to-github).
+
+### Install Docker
+
+Before you start, make sure that you have [installed Docker](+software_reference#docker).
+
+
+### Fork the `docs-![book]` repo on the Github site
+
+Fork one of the `docs-![book]` repos on the Github site ([](#fork-duckuments)).
+
+This will create a new repo on your account that is linked to the original one.
+
+<figure id="fork-duckuments">
+ <img src="fork-duckuments.png" style='width: 80%'/>
+</figure>
+
+TODO: re-make image
+
+### Checkout your fork locally
+
+Check out the forked repository as you would do normally.
+
+### Do your edits
+
+Do your edits on your local copy.
+
+### Compile
+
+Compile using:
+
+```
+$ make compile-docker
+```
+
+### Commit and push
+
+Commit and push as you would do normally.
+
+### Make a pull request
+
+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 
+
+#### Option 2: Use the command-line program `hub`
+
+You can create a pull request from the command-line using [`hub`](+software_reference#hub):
+
+```
+$ hub pull-request
+```
+
+See: [](+software_reference#hub)
+
+
+## Using CircleCI
+
+Circle CI makes it easier to check whether there are problems to be fixed.
+
+### Sign up on Circle
+
+Sign up on the Circle CI service, at the link [circleci.com](http://circleci.com).
+
+### Activate your build on Circle
+
+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.
+
+<figure id="ci-artifacts">
+ <img src='ci-artifacts.png' style='width:90%'/>
+</figure>
+
+
+## Reporting problems
+
+First, see the section [](#markduck-troubleshooting) for common problems and their resolution.
+
+Please report problems with the duckuments using [the `duckuments` issue tracker][tracker].
+
+[tracker]: https://github.com/duckietown/duckuments/issues
+
+Special notes:
+
+* If you have a problem with a generated PDF, please attach the offending PDF.
+* If you say something like "This happens for Figure 3", then it is hard to know which figure you are referencing exactly, because numbering changes from commit to commit.
+
+
+If you want to refer to specific parts of the text, please commit all your work on your branch, and obtain the name of the commit using the following commands:
+
+```
+$ git -C ~/duckuments rev-parse HEAD      # commit for duckuments
+$ git -C ~/duckuments/mcdp rev-parse HEAD # commit for mcdp
+```

book/duckumentation/10_contributing/58_markdown_editors.md → book/duckumentation/10_contributing/50_markdown_editors.md

@@ -17,8 +17,8 @@ Typhora is our favorite beacause it allows to preview LaTeX formulas.
 
 ## Atom
 
-See: [](#atom)
+See: [](+software_reference#atom)
 
 ## PyCharm
 
-See: [](#pycharm)
+See: [](+software_reference#pycharm)