done

amackeith · Jun 2, 2018 · b8e4282 · b8e4282
commit b8e4282
Show file tree

Hide file tree

Showing 35 changed files with 2,352 additions and 0 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -0,0 +1,45 @@
+version: 2
+jobs:
+    build:
+        docker:
+        - image: andreacensi/mcdp_manual:1
+          environment:
+              COLUMNS: 160
+
+              MPLBACKEND: agg
+
+        resource_class: large
+        steps:
+        - checkout
+        - run:
+            name: virtualenv
+            command: |
+                ln -s /project/deploy deploy
+
+        - run:
+            name: Compile all books
+            command: |
+                make
+#
+#        - run:
+#            name: Create index of webpage
+#            command: |
+#              make summaries
+
+#        - 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
+#
+#        - test-results-store:
+#            path: duckuments-dist/junit
+#
+#        - store_artifacts:
+#              path: duckuments-dist
+#              destination: duckuments-dist
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1,25 @@
+*.pdf filter=lfs diff=lfs merge=lfs -text
+*.PDF filter=lfs diff=lfs merge=lfs -text
+*.xlsx filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.JPG filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.PNG filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.JPEG filter=lfs diff=lfs merge=lfs -text
+*.docx filter=lfs diff=lfs merge=lfs -text
+*.pptx filter=lfs diff=lfs merge=lfs -text
+*.key filter=lfs diff=lfs merge=lfs -text
+*.mp4 filter=lfs diff=lfs merge=lfs -text
+*.svg filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.mp4 filter=lfs diff=lfs merge=lfs -text
+*.eps filter=lfs diff=lfs merge=lfs -text
+*.ipt filter=lfs diff=lfs merge=lfs -text
+*.stl filter=lfs diff=lfs merge=lfs -text
+*.SLDPRT filter=lfs diff=lfs merge=lfs -text
+*.ai filter=lfs diff=lfs merge=lfs -text
+*.SLDASM filter=lfs diff=lfs merge=lfs -text
+*.SLDDRW filter=lfs diff=lfs merge=lfs -text
+*.STL filter=lfs diff=lfs merge=lfs -text
+*.world filter=lfs diff=lfs merge=lfs -text
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,2 @@
+out
+duckuments-dist
diff --git a/Makefile b/Makefile
@@ -0,0 +1,6 @@
+
+compile-native:
+	./run-book-native.sh duckumentation docs
+
+compile-docker:
+	./run-book-docker.sh duckumentation docs
diff --git a/docs/00_book_contribute.md b/docs/00_book_contribute.md
@@ -0,0 +1,5 @@
+# Duckumentation documentation {#book:contribute status=ready}
+
+Maintainer: Andrea Censi
+
+This book describes the features of our documentation system and the procedures to update it.
diff --git a/docs/00_main_template.html b/docs/00_main_template.html
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <title>The Duckietown book</title>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+    <meta name="google-site-verification" content="JtEkVR2TrLbne9-4YPHmzIqCeagG15FhWCnw1PUis-Q"/>
+    <link rel="icon" href="https://www2.duckietown.org/wp-content/uploads/2018/05/cropped-duckie2-192x192.png" sizes="192x192" />
+
+    <script>
+        (function (i, s, o, g, r, a, m) {
+            i['GoogleAnalyticsObject'] = r;
+            i[r] = i[r] || function () {
+                (i[r].q = i[r].q || []).push(arguments)
+            }, i[r].l = 1 * new Date();
+            a = s.createElement(o),
+                m = s.getElementsByTagName(o)[0];
+            a.async = 1;
+            a.src = g;
+            m.parentNode.insertBefore(a, m)
+        })(window, document, 'script', 'https://www.google-analytics.com/analytics.js', 'ga');
+        ga('create', 'UA-119606699-2', 'auto');
+        ga('send', 'pageview');
+    </script>
+    <style>
+        h1:not([id^="book"]) {
+            page-break-before: always;
+        }
+
+        .purl_link {
+            display:none;
+        }
+        #tocdiv {
+            position: fixed !important;
+            overflow: scroll;
+            /*height: 80vh;*/
+            overflow-x: hidden;
+            overflow-y: auto;
+        }
+
+        .link-same-file-direct-parent.toc_li_for_unknown .toc_li_for_part {
+            display: none;
+        }
+
+    </style>
+    <link rel="stylesheet" type="text/css" media="screen" href="duckietown.css"/>
+</head>
+<body>
+</body>
+</html>
diff --git a/docs/10_contributing/00_part_contributing.md b/docs/10_contributing/00_part_contributing.md
@@ -0,0 +1,3 @@
+# Contributing to the documentation {#part:contribute-to-docs status=ready level=part}
+
+This part describes the workflow for contributing to our documentation.
diff --git a/docs/10_contributing/10_intro.md b/docs/10_contributing/10_intro.md
@@ -0,0 +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 written as a series of small files in Markdown format.
+
+It is then processed by a series of scripts to create  publication-quality PDF and an online HTML version.
+
+You can find all these artifacts produced at the site [`docs.duckietown.org`](http://docs.duckietown.org).
+
+## Editing links
+
+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.
diff --git a/docs/10_contributing/55_installation.md b/docs/10_contributing/55_installation.md
@@ -0,0 +1,110 @@
+# Installation and compilation {#duckumentation-installing-docs-system status=ready}
+
+In the following, we are going to assume that the documentation system is installed in `~/duckuments`. However, it can be installed anywhere.
+
+We are also going to assume that you have setup a Github account with working public keys.
+
+See: [Basic SSH config](#ssh-local-configuration).
+
+See: [Key pair creation](#howto-create-key-pair).
+
+See: [Adding public key on Github](#howto-add-pubkey-to-github).
+
+### Download the `duckuments` repo
+
+Download the `duckietown/duckuments` repository in the `~/duckuments` directory:
+
+```
+$ git clone --depth 11 [email protected]:duckietown/duckuments ~/duckuments
+$ cd ~/duckuments
+$ git submodule init
+$ git submodule update --recursive 
+```
+
+Here, note we are using `git lfs clone` -- it's much faster, because it downloads the Git LFS files in parallel.
+
+If it fails, it means that you do not have Git LFS installed. See [](#git-lfs).
+
+The command `--depth 10` tells it we do not care about the whole history.
+
+### Setup the virtual environment
+
+Use this to install a virtual environment and dependencies:
+
+```
+$ cd ~/duckuments
+$ make dependencies-ubuntu16
+$ make install-ubuntu16
+```
+
+For other distributions, you might need to modify the `install-ubuntu16` Makefile recipe (e.g. use `venv` instead of `virtualenv`).
+
+## Compiling the documentation   {#compiling-master}
+
+### Compiling all the books
+
+To compile everything from scratch, run:
+
+```
+$ make realclean all
+```
+
+To see the results, open the file
+
+```
+~/duckuments/duckuments-dist/index.html
+```
+
+If you want to do incremental compilation, you can omit the `clean` and just use:
+
+```
+$ make all
+```
+
+### Compiling a single book
+
+After you have compiled all the books,  you can use one of the following commands to re-compile one single book:
+
+```
+$ make book-duckumentation
+$ make book-the_duckietown_project
+$ make book-opmanual_duckiebot_base
+$ make book-opmanual_duckiebot_fancy
+$ make book-opmanual_duckietown
+$ make book-software_carpentry
+$ make book-software_devel
+$ make book-software_architecture
+$ make book-class_fall2017
+$ make book-class_fall2017_projects
+$ make book-learning_materials
+$ make book-exercises
+$ make book-drafts
+$ make book-guide_for_instructors
+$ make book-deprecated
+$ make book-preliminaries
+```
+
+The compilation is always incremental, but sometimes you might need to do a reset using:
+
+```
+$ make realclean
+```
+
+## 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
+```
diff --git a/docs/10_contributing/57_workflow.md b/docs/10_contributing/57_workflow.md
@@ -0,0 +1,96 @@
+# Workflow to edit documentation  {#duckumentation-workflow status=ready}
+
+This section describes the workflow to edit the documentation collaboratively.
+
+We make the following assumptions:
+
+* Every writer has a Github account with username `![username]`.
+* Every writer will *fork* the `duckuments` repo to their Github account.
+* All contributions are pull requests.
+* [Optional] Every writer will sign up on Circle CI. This will make it easier to check whether there are problems to be fixed.
+
+## Workflow
+
+### Fork the `duckuments` repo on the Github site
+
+For the `duckuments` repo on the Github site ([](#fork-duckuments)).
+
+<img src="fork-duckuments.png" style='width: 80%' figure-id="fig:fork-duckuments"/>
+
+This will create a new repo on your account that is linked to the original one.
+
+### [optional] Sign up on Circle
+
+Sign up on the Circle CI service, at the link [circleci.com](http://circleci.com).
+
+### [optional] 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".
+
+### Checkout your fork locally
+
+Check out the forked repository as you would do normally.
+
+### Do your edits
+
+Do your edits on your
+
+### Compile
+
+Compile using:
+
+```
+$ make all
+```
+
+You can also compile a single book using:
+
+```
+$ make book-![book name]
+```
+
+Type TAB after `book-` to see the list of books.
+
+### Commit and push
+
+Commit and push as you would do normally.
+
+####  [optional] 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.
+
+<img src='ci-artifacts.png' style='width:90%' figure-id="fig:ci-artifacts"/>
+
+### 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.
+
+#### Option 2: Use the command-line program `hub`
+
+You can create a pull request from the command-line using [`hub`](#hub):
+
+```
+$ hub pull-request
+```
+
+See: [](#hub)
diff --git a/docs/10_contributing/58_markdown_editors.md b/docs/10_contributing/58_markdown_editors.md
@@ -0,0 +1,24 @@
+# Markdown editors {#duckumentation-editors status=ready}
+
+We suggest the following:
+
+* Find a visual Markdown editor that you like.
+* Complement with a superb text-only editor.
+
+## Graphical Markdown editors
+
+### Typhora
+
+Typhora is our favorite beacause it allows to preview LaTeX formulas.
+
+<dtvideo src="vimeo:267112016"/>
+
+## Text editors good for Markdown
+
+## Atom
+
+See: [](#atom)
+
+## PyCharm
+
+See: [](#pycharm)
diff --git a/docs/10_contributing/ci-artifacts.png b/docs/10_contributing/ci-artifacts.png
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Contributing to the documentation {#part:contribute-to-docs status=ready level=part}

		This part describes the workflow for contributing to our documentation.