diff --git a/.circleci/config.yml b/.circleci/config.yml new file mode 100644 index 0000000..c489823 --- /dev/null +++ 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 new file mode 100644 index 0000000..ee4911d --- /dev/null +++ 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 new file mode 100644 index 0000000..a13a494 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +out +duckuments-dist diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..d75455d --- /dev/null +++ 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 new file mode 100644 index 0000000..8197da5 --- /dev/null +++ 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 new file mode 100644 index 0000000..39023be --- /dev/null +++ b/docs/00_main_template.html @@ -0,0 +1,50 @@ + + + + + The Duckietown book + + + + + + + + + + + diff --git a/docs/10_contributing/00_part_contributing.md b/docs/10_contributing/00_part_contributing.md new file mode 100644 index 0000000..f10fdc7 --- /dev/null +++ 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 new file mode 100644 index 0000000..cd4b7cf --- /dev/null +++ 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 new file mode 100644 index 0000000..0a64cf0 --- /dev/null +++ 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 git@github.com: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 new file mode 100644 index 0000000..b41d935 --- /dev/null +++ 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)). + + + +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. + + + +### 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 new file mode 100644 index 0000000..be8167f --- /dev/null +++ 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. + + + +## 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 new file mode 100644 index 0000000..a4cf414 --- /dev/null +++ b/docs/10_contributing/ci-artifacts.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6f4adb382b3b3a792b3e879ba718ebfe97678cbb5a76755bcf9214f597c0a362 +size 193104 diff --git a/docs/10_contributing/fork-duckuments.png b/docs/10_contributing/fork-duckuments.png new file mode 100644 index 0000000..eee4c32 --- /dev/null +++ b/docs/10_contributing/fork-duckuments.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:06694858b87f573aea54e46c6ba5cc29814d83944d58151e3fb4b00ec62801df +size 240162 diff --git a/docs/20_markduck/00_part_markduck.md b/docs/20_markduck/00_part_markduck.md new file mode 100644 index 0000000..a7a33fc --- /dev/null +++ b/docs/20_markduck/00_part_markduck.md @@ -0,0 +1,3 @@ +# Markduck format {#part:markduck status=ready} + +This part describes the Markdown dialect that is used in the documentation. diff --git a/docs/20_markduck/65_docs_features.md b/docs/20_markduck/65_docs_features.md new file mode 100644 index 0000000..9151326 --- /dev/null +++ b/docs/20_markduck/65_docs_features.md @@ -0,0 +1,488 @@ +# Basic Markduck guide {#markduck-basic status=ready} + +The Duckiebooks are written in Markduck, a Markdown dialect. + +It supports many features that make it possible to create publication-worthy materials. + + +## Markdown + +The Duckiebook are written in a Markdown dialect. + +See: [A tutorial on Markdown][tutorial]. + +[tutorial]: https://www.markdowntutorial.com/ + + + +## Variables in command lines and command output + +Use the syntax "![name]" for describing the variables in the code. + +
+ +For example, to obtain: + + $ ssh ![robot name].local + +Use the following: + +
+
+For example, to obtain:
+
+    $ ssh ![robot name].local
+
+
+
+ +
+ +Make sure to quote (with 4 spaces) all command lines. Otherwise, the dollar symbol confuses the +LaTeX interpreter. + + + +## Character escapes + +Use the string &#36; to write the dollar symbol +$, otherwise it gets confused with LaTeX math materials. Also notice +that you should probably use "USD" to refer to U.S. dollars. + +Other symbols to escape are shown in [](#tab:escapes). + + + use &#36; instead of $ + use &#96; instead of ` + use &#lt; instead of < + use &#gt; instead of > + + + +## Keyboard keys + +Use the `kbd` element for keystrokes. + +
+ +For example, to obtain: + +> Press a then Ctrl-C. + +use the following: + +```markdown +Press a then Ctrl-C. +``` + +
+ +## Figures {#figures} + +To create a figure, use the element `figure`: + +```html +
+
Hello
+ +
+``` + +
+
Hello
+ +
+ +### More attributes + +Use `class="caption-left"` to have the caption show up on the left rather than on the bottom: + +```html +
+
Hello
+ +
+``` + +
+
Hello
+ +
+ + +## Subfigures + +You can create subfigures by nesting `figure` elements: + +```html +
+
Main caption
+
+
Hello
+ +
+
+
second
+ +
+
+``` + +
+
Main caption
+
+
Hello
+ +
+
+
second
+ +
+
+ +By default, they are displayed one per block. +To make them flow horizontally, add `class="flow-subfigures"` to the external figure: + +```html +
+
Main caption
+
+
Hello
+ +
+
+
second
+ +
+
+``` + +
+
Main caption
+
+
Hello
+ +
+
+
second
+ +
+
+ + + + +For any element, adding an attribute called `figure-id` with value `fig:![figure ID]` or `tab:![table ID]` will create a figure that wraps the element. + + + + + +## Shortcut for tables + +The shortcuts `col2`, `col3`, `col4`, `col5` +are expanded in tables with 2, 3, 4 or 5 columns. + +The following code: + +
+
+<col2 figure-id="tab:mytable" figure-caption="My table">
+    <span>A</span>
+    <span>B</span>
+    <span>C</span>
+    <span>D</span>
+</col2>
+
+
+ + + + +gives the following result: + + + A + B + C + D + + +### `labels-row1` and `labels-row1` + +Use the classes `labels-row1` and `labels-row1` to make pretty tables like the following. + +`labels-row1`: the first row is the headers. + +`labels-col1`: the first column is the headers. + + +
Using class="labels-col1"
+ header A + B + C + 1 + header D + E + F + 2 + header G + H + I + 3 + + + +
Using class="labels-row1"
+ header A + header B + header C + D + E + F + G + H + I + 1 + 2 + 3 + + +## Linking to documentation {#linking-to-documentation} + +### Establishing names of headers {#establishing} + +You give IDs to headers using the format: + +```markdown +### ![header title] {#![topic ID]} +``` + +For example, for this subsection, we have used: + +```markdown +### Establishing names of headers {#establishing} +``` + +With this, we have given this header the ID "`establishing`". + + +### How to name IDs - and why it's not automated + +Some time ago, if there was a section called + +```markdown +## My section +``` + +then it would be assigned the ID "my-section". + +This behavior has been removed, for several reasons. + +One is that if you don't see the ID then you will be tempted to just change the name: + +```markdown +## My better section +``` + +and silently the ID will be changed to "my-better-section" and all the previous links will be invalidated. + +The current behavior is to generate an ugly link like "autoid-209u31j". + +This will make it clear that you cannot link using the PURL if you don't assign an ID. + + +Also, I would like to clarify that all IDs are *global* (so it's easy to link stuff, without thinking about namespaces, etc.). + +Therefore, please choose descriptive IDs, with at least two IDs. + +E.g. if you make a section called + +```markdown +## Localization {#localization} +``` + +that's certainly a no-no, because "localization" is too generic. + +Better: + +```markdown +## Localization {#intro-localization} +``` + +Also note that you don't *need* to add IDs to everything, only the things that people could link to. (e.g. not subsubsections) + + +### Linking from the documentation to the documentation + +You can use the syntax: + + + [](#![topic ID]) + + +to refer to the header. + +You can also use some slightly more complex syntax that also allows +to link to only the name, only the number or both ([](#tab:link-examples)). + + + 
See [](#establishing).
+ See + 
See <a class="only_name" href="#establishing"></a>.
+ See . + 
See <a class="only_number" href="#establishing"></a>.
+ See . + 
See <a class="number_name" href="#establishing"></a>.
+ See . + + + + +### Linking to the documentation from outside the documentation + +You are encouraged to put links to the documentation from the code or scripts. + +To do so, use links of the form: + + http://purl.org/dth/![topic ID] + +Here "`dth`" stands for "Duckietown Help". This link will get redirected to +the corresponding document on the website. + +For example, you might have a script whose output is: + + $ rosrun mypackage myscript + Error. I cannot find the scuderia file. + See: http://purl.org/dth/scuderia + +When the user clicks on the link, they will be redirected to [](#scuderia). + +## Comments + +You can insert comments using the HTML syntax for comments: +any text between "<!--" and "-->" is ignored. + +
+
+# My section
+
+<!-- this text is ignored -->
+
+Let's start by...
+
+
diff --git a/docs/20_markduck/66_special_envs.md b/docs/20_markduck/66_special_envs.md new file mode 100644 index 0000000..d45e4fe --- /dev/null +++ b/docs/20_markduck/66_special_envs.md @@ -0,0 +1,297 @@ +# Special paragraphs and environments {#markduck-special-pars status=ready label-name="Special paragraphs"} + +## Special paragraphs tags {#special-paragraphs} + +The system supports parsing of some special paragraphs. + +Note: some of these might be redundant and will be eliminated. For now, +I am documenting what is implemented. + + +### Special paragraphs must be separated by a line {#empty-line-before-special} + +A special paragraph is marked by a special prefix. +The list of special prefixes is given in the next section. + +There must be an empty line before a special paragraph; +this is because in Markdown a paragraph starts only after an empty line. + +This is checked automatically, and the compilation will abort if the mistake is found. + +For example, this is invalid: + + See: this book + See: this other book + +This is correct: + + See: this book + + See: this other book + +Similarly, this is invalid: + + Author: author + Maintainer: maintainer + +and this is correct: + + Author: author + + Maintainer: maintainer + + +### Todos, task markers + + TODO: todo + +TODO: todo + + TOWRITE: towrite + +TOWRITE: towrite + + Task: task + +Task: task + + Assigned: assigned + +Assigned: assigned + + + +### Notes and remarks + + Remark: remark + +Remark: remark + + Note: note + +Note: note + + Warning: warning + +Warning: warning + + +### Troubleshooting + + Symptom: symptom + +Symptom: symptom + + Resolution: resolution + +Resolution: resolution + +### Guidelines + + Bad: bad + +Bad: bad + + Better: better + +Better: better + +### Questions and answers + + Q: question + +Q: question + + A: answer + +A: answer + + +### Authors, maintainers, Point of Contact + + Maintainer: maintainer + +Maintainer: maintainer + + Assigned: AndreaCensi + +Assigned: AndreaCensi + + + +### References + + + See: see + +See: see + + Reference: reference + +Reference: reference + + Requires: requires + +Requires: requires + + Results: results + +Results: results + + Next steps: next steps + +Next steps: next steps + + Recommended: recommended + +Recommended: recommended + + See also: see also + +See also: see also + + + +## Other `div` environments {#div-environments} + +For these, note the rules: + +- You must include `markdown="1"`. +- There must be an empty line after the first `div` and before the closing `/div`. + +### Example usage + +
+ + This is how you can use `rosbag`: + + $ rosbag play log.bag + +
+ +
+ +This is how you can use `rosbag`: + + + $ rosbag play log.bag + +
+ +### Check + + +
+ + Check that you didn't forget anything. + +
+ +
+ +Check that you didn't forget anything. + +
+ +### Requirements + +
+ + List of requirements at the beginning of setup chapter. + +
+ +
+ +List of requirements at the beginning of setup chapter. + +
+ +## Notes and questions {#notes-and-questions} + +There are three environments: "comment", "question", "doubt", +that result in boxes that can be expanded by the user. + +These are the one-paragraph forms: + + Comment: this is a comment on one paragraph. + +Comment: this is a comment on one paragraph. + + Question: this is a question on one paragraph. + +Question: this is a question on one paragraph. + + Doubt: I have my doubts on one paragraph. + +Doubt: I have my doubts on one paragraph. + +These are the multiple-paragraphs forms: + + +
+ A comment... + + A second paragraph... +
+ +
+A comment... + +A second paragraph... +
+ + +
+ A question... + + A second paragraph... +
+ +
+A question... + +A second paragraph... +
+ + +
+ A question... + + Should it not be: + + $ alternative command + + A second paragraph... +
+ + +
+A question... + +Should it not be: + + $ alternative command + +A second paragraph... +
diff --git a/docs/20_markduck/67_latex_features.md b/docs/20_markduck/67_latex_features.md new file mode 100644 index 0000000..545d959 --- /dev/null +++ b/docs/20_markduck/67_latex_features.md @@ -0,0 +1,235 @@ +# Using LaTeX constructs in documentation {#markduck-latex status=ready label-name="LaTeX constructs"} + +
+ +Requires: Working knowledge of LaTeX. + +
+ +## Embedded LaTeX + +You can use $\LaTeX$ math, environment, and references. For example, take a look at + +\[ + x^2 = \int_0^t f(\tau)\ \text{d}\tau +\] + +or refer to [](#prop:example). + +\begin{proposition}[Proposition example]\label{prop:example} +This is an example proposition: $2x = x + x$. +\end{proposition} + +The above was written as in [](#code:latex-code). + +
+
+You can use $\LaTeX$ math, environment, and references.
+For example, take a look at
+
+\[
+    x^2 = \int_0^t f(\tau)\ \text{d}\tau
+\]
+
+or refer to [](#prop:example).
+
+\begin{proposition}[Proposition example]\label{prop:example}
+This is an example proposition: $2x = x + x$.
+\end{proposition}
+
+
+ +For the LaTeX environments to work properly you *must* add a `\label` +declaration inside. Moreover, the label must have a prefix that is adequate +to the environment. For example, for a proposition, you must insert `\label{prop:![name]}` +inside. + +The following table shows the list of the LaTeX environments supported +and the label prefix that they need. + + + definition + def:![name] + proposition + prop:![name] + remark + rem:![name] + problem + prob:![name] + theorem + thm:![name] + lemma + lem:![name] + + + +Examples of all environments follow. + +
+ + 
\begin{definition}   \label{def:lorem}
+Lorem
+\end{definition}
+ +\begin{definition}\label{def:lorem}Lorem\end{definition} + + 
\begin{proposition}   \label{prop:lorem}
+Lorem
+\end{proposition}
+ +\begin{proposition}\label{prop:lorem}Lorem\end{proposition} + + 
\begin{remark}   \label{rem:lorem}
+Lorem
+\end{remark}
+ +\begin{remark}\label{rem:lorem}Lorem\end{remark} + + 
\begin{problem}    \label{prob:lorem}
+Lorem
+\end{problem}
+ +\begin{problem}\label{prob:lorem}Lorem\end{problem} + + 
\begin{example}   \label{exa:lorem}
+Lorem
+\end{example}
+ +\begin{example}\label{exa:lorem}Lorem\end{example} + + 
\begin{theorem}   \label{thm:lorem}
+Lorem
+\end{theorem}
+ +\begin{theorem}\label{thm:lorem}Lorem\end{theorem} + + 
\begin{lemma}   \label{lem:lorem}
+Lorem
+\end{lemma}
+ +\begin{lemma}\label{lem:lorem}Lorem\end{lemma} + + I can also refer to all of them: + [](#def:lorem), + [](#prop:lorem), + [](#rem:lorem), + [](#prob:lorem), + [](#exa:lorem), + [](#thm:lorem), + [](#lem:lorem). + +I can also refer to all of them: +[](#def:lorem), +[](#prop:lorem), +[](#rem:lorem), +[](#prob:lorem), +[](#exa:lorem), +[](#thm:lorem), +[](#lem:lorem). + +
+ +## LaTeX equations {#latex-equations} + +We can refer to equations, such as \eqref{eq:one}: + +\begin{equation} + 2a = a + a \label{eq:one} +\end{equation} + +This uses `align` and contains \eqref{eq:two} and \eqref{eq:three}. + +\begin{align} + a &= b \label{eq:two} \\ + &= c \label{eq:three} +\end{align} + +
+
+We can refer to equations, such as \eqref{eq:one}:
+
+\begin{equation}
+    2a = a + a          \label{eq:one}
+\end{equation}
+
+This uses `align` and contains  \eqref{eq:two} and \eqref{eq:three}.
+
+\begin{align}
+    a &= b       \label{eq:two} \\
+      &= c       \label{eq:three}
+\end{align}
+
+
+ +Note that referring to the equations is done using the syntax `\eqref{eq:![name]}`, +rather than `[](#eq:![name])`. + + +## LaTeX symbols + +The LaTeX symbols definitions are in a file called [`docs/symbols.tex`][symbols]. + + +[symbols]: github:org=Duckietown,repo=duckuments,path=docs/symbols.tex + + +Put all definitions there; if they are centralized it is easier to check +that they are coherent. + + +## Bibliography support {#bibliography-support} + +You need to have installed `bibtex2html`. + +The system supports Bibtex files. + +Place `*.bib` files anywhere in the directory. + +Then you can refer to them using the syntax: + + [](#bib:![bibtex ID]) + +For example: + + Please see [](#bib:siciliano07handbook). + +Will result in: + +> Please see [](#bib:siciliano07handbook). + +## Embedding Latex in Figures through SVG {#svg-figures} + +
+ +Requires: In order to compile the figures into PDFs you need to have Inkscape installed. Instructions to download and install Inkscape are [here](https://inkscape.org/en/release/0.92.2/). + +
+ + +To embed latex in your figures, you can add it directly to a file and save it as `![filename].svg` file and save anywhere in the `/docs` directory. + +You can run: + + $ make process-svg-figs + +And the SVG file will be compiled into a PDF figure with the LaTeX commands properly interpreted. + +You can then include the PDF file in a normal way ([](#figures)) using `![filename].pdf` as the filename in the <img> tag. + + +
+
Embedding LaTeX in images
+ +
+
Image saved as svg
+ +
+
+
Image as PDF after processing
+ +
+
+ + + +It can take a bit of work to get the positioning of the code to appear properly on the figure. diff --git a/docs/20_markduck/68_advanced_guide.md b/docs/20_markduck/68_advanced_guide.md new file mode 100644 index 0000000..ef6529c --- /dev/null +++ b/docs/20_markduck/68_advanced_guide.md @@ -0,0 +1,51 @@ + +# Embedding videos {#markduck-vimeo status=ready} + +It is possible to embed Vimeo videos in the documentation. + +Note: Do not upload the videos to your personal Vimeo account; they must all be +posted to the Duckietown Engineering account. + +This is the syntax: + + + +
+ +For example, this code: + +
+
Cool Duckietown by night
+ +
+ +produces this result: + +
+
Cool Duckietown by night
+ +
+ +
+ + +Depending on the output media, the result will change: + +* On the online book, the result is that a player is embedded. +* On the e-book version, the result is that a thumbnail is produced, with a link to the video; +* (future improvement) On the dead-tree version, a thumbnail is produced with a QR code linking to the video. + + +# `move-here` tag {#move-here status=deprecated} + +Note: This feature is deprecated, as it causes more problems than it solves. + +If a file contains the tag `move-here`, the fragment pointed by the `src` attribute is moved at the place of the tag. + +This is used for autogenerated documentation. + +Syntax: + + # Node `node` + + diff --git a/docs/20_markduck/69_github.md b/docs/20_markduck/69_github.md new file mode 100644 index 0000000..0231f4f --- /dev/null +++ b/docs/20_markduck/69_github.md @@ -0,0 +1,98 @@ +# Referring to Github files {#markduck-github status=ready} + +You can refer to files in the repository by using: + + See [this file](github:org=![org],repo=![repo],path=![path],branch=![branch]). + +The available keys are: + +- `org` (required): organization name (e.g. `duckietown`); +- `repo` (required): repository name (e.g. `Software`); +- `path` (required): the filename. Can be just the file name or also include directories; +- `branch` (optional) the repository branch; defaults to `master`; + + +For example, you can refer to [the file `pkg_name/src/subscriber_node.py`][link1] by using the following syntax: + +[link1]: github:org=duckietown,repo=Software,path=pkg_name/src/subscriber_node.py + + See [this file](github:org=duckietown,repo=Software,path=pkg_name/src/subscriber_node.py) + +You can also refer to a particular line: + +This is done using the following parameters: + +- `from_text` (optional): reference the first line containing the text; +- `from_line` (optional): reference the line by number; + + +For example, you can refer to [the line containing "Initialize"][link2] +of `pkg_name/src/subscriber_node.py` by using the following syntax: + +[link2]: github:org=duckietown,repo=Software,path=pkg_name/src/subscriber_node.py,from_text=Initialize + + + For example, you can refer to [the line containing "Initialize"][link2] + of `pkg_name/src/subscriber_node.py` by using the following syntax: + + [link2]: github:org=duckietown,repo=Software,path=pkg_name/src/subscriber_node.py,from_text=Initialize + + +You can also reference a range of lines, using the parameters: + +- `to_text` (optional): references the final line, by text; +- `to_line` (optional): references the final line, by number. + +You cannot give `from_text` and `from_line` at the same time. +You cannot give a `to_...` without the `from_...`. + +For example, [this link refers to a range of lines][interval]: click it to see how Github highlights the lines from "Initialize" to "spin". + +[interval]: github:org=duckietown,repo=Software,path=pkg_name/src/subscriber_node.py,from_text=Initialize,to_text=spin + +This is the source of the previous paragraph: + + For example, [this link refers to a range of lines][interval]: click it to see how Github highlights the lines from "Initialize" to "spin". + + [interval]: github:org=duckietown,repo=Software,path=pkg_name/src/subscriber_node.py,from_text=Initialize,to_text=spin + + +## Putting code from the repository in line + +In addition to referencing the files, you can also copy the contents of a file inside the documentation. + +This is done by using the tag `display-file`. + +For example, you can put a copy of `pkg_name/src/subscriber_node.py` using: + + + +and the result is the following automatically generated listing: + + + +If you use the `from_text` and `to_text` (or `from_line` and `to_line`), you can actually display part of a file. For example: + + + +creates the following automatically generated listing: + + diff --git a/docs/20_markduck/69_markduck_troubleshooting.md b/docs/20_markduck/69_markduck_troubleshooting.md new file mode 100644 index 0000000..acda2c9 --- /dev/null +++ b/docs/20_markduck/69_markduck_troubleshooting.md @@ -0,0 +1,51 @@ +# Troubleshooting {#markduck-troubleshooting status=ready} + +## Troubleshooting errors in the compilation process + +Symptom: "Invalid XML" + +Resolution: "Markdown" doesn't mean that you can put anything in a file. Except +for the code blocks, it must be valid XML. For example, if you use +">" and "<" without quoting, it will likely +cause a compile error. + +Symptom: "Tabs are evil" + +Resolution: Do not use tab characters. The error message in this case is quite +helpful in telling you exactly where the tabs are. + + +Symptom: The error message contains `ValueError: Suspicious math fragment 'KEYMATHS000ENDKEY'` + +Resolution: You probably have forgotten to indent a command line by at least 4 spaces. The dollar in the command line is now being confused for a math formula. + + +## Common mistakes with Markdown {#common-markdown-mistakes} + +Here are some common mistakes encountered. + +### Not properly starting a list {#invalid-list} + +There must be an empty line before the list starts. + +This is correct: + + I want to learn: + + - robotics + - computer vision + - underwater basket weaving + +This is incorrect: + + I want to learn: + - robotics + - computer vision + - underwater basket weaving + +and it will be rendered as follows: + +I want to learn: +- robotics +- computer vision +- underwater basket weaving diff --git a/docs/20_markduck/duckietown-logo-transparent.png b/docs/20_markduck/duckietown-logo-transparent.png new file mode 100644 index 0000000..0b05e6b --- /dev/null +++ b/docs/20_markduck/duckietown-logo-transparent.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:049eece86365e244716d25b5fcfbb66553753d16858182161f08539127291a3b +size 50877 diff --git a/docs/20_markduck/example.bib b/docs/20_markduck/example.bib new file mode 100644 index 0000000..5a6bf0e --- /dev/null +++ b/docs/20_markduck/example.bib @@ -0,0 +1,13 @@ + + + +@book{siciliano07handbook, + author = {Siciliano, Bruno and Khatib, Oussama}, + title = {Springer Handbook of Robotics}, + year = {2007}, + isbn = {354023957X}, + publisher = {Springer-Verlag New York, Inc.}, + address = {Secaucus, NJ, USA}, +} + + diff --git a/docs/20_markduck/sample-no-process.converted.png b/docs/20_markduck/sample-no-process.converted.png new file mode 100644 index 0000000..a1510e8 --- /dev/null +++ b/docs/20_markduck/sample-no-process.converted.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0f50decb4bd64816c7a73812a1c39b5c9a21754078cef809160c5d64d8ec7779 +size 2895 diff --git a/docs/20_markduck/sample-no-process.pdf b/docs/20_markduck/sample-no-process.pdf new file mode 100644 index 0000000..d6a064b Binary files /dev/null and b/docs/20_markduck/sample-no-process.pdf differ diff --git a/docs/20_markduck/sample.svg b/docs/20_markduck/sample.svg new file mode 100644 index 0000000..7186475 --- /dev/null +++ b/docs/20_markduck/sample.svg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:48faf9b57e4677aaa151bd751b03ee1a2e0e5e53f6b61001a6647ece1bae7125 +size 4084 diff --git a/docs/30_style_guide/00_part_style.md b/docs/30_style_guide/00_part_style.md new file mode 100644 index 0000000..fea8b4b --- /dev/null +++ b/docs/30_style_guide/00_part_style.md @@ -0,0 +1,3 @@ +# Documentation style guide {#part:style-guide status=ready} + +This part describes the style guide for our documentation. diff --git a/docs/30_style_guide/76_style_guide.md b/docs/30_style_guide/76_style_guide.md new file mode 100644 index 0000000..2e73e07 --- /dev/null +++ b/docs/30_style_guide/76_style_guide.md @@ -0,0 +1,144 @@ + + +# Style guide {#documentation-style-guide status=ready} + +This chapter describes the conventions for writing the technical documentation. + +## General guidelines for technical writing + +The following holds for all technical writing. + +- The documentation is written in correct English. + +- Do not say "should" when you mean "must". "Must" and "should" have precise + meanings and they are not interchangeable. + These meanings are explained [in this document][rfc]. + +[rfc]: https://www.ietf.org/rfc/rfc2119.txt + +- "Please" is unnecessary in technical documentation. + +> Bad: "Please remove the SD card." + +> Better: "Remove the SD card". + +- Do not use colloquialisms or abbreviations. + +> Bad: "The pwd is `ubuntu`." + +> Better: "The password is `ubuntu`." + +> Bad: "To create a ROS pkg..." + +> Better: "To create a ROS package..." + +- Python is capitalized when used as a name. + +> Bad: "If you are using python..." + +> Better: "If you are using Python..." + +- Do not use emojis. + +- Do not use ALL CAPS. + +- Make infrequent use of **bold statements**. + +- Do not use exclamation points. + +## Style guide for the Duckietown documentation + +- The English version of the documentation is written in American English. Please note that your spell checker might be set to British English. + +Bad: behaviour + +Better: behavior + +Bad: localisation + +Better: localization + + +- It's ok to use "it's" instead of "it is", "can't" instead of "cannot", etc. + +- All the filenames and commands must be enclosed in code blocks using Markdown backticks. + +> Bad: "Edit the ~/.ssh/config file using vi." + +> Better: "Edit the `~/.ssh/config` file using `vi`." + +- Ctrl-C, `ssh` etc. are not verbs. + +> Bad: "Ctrl-C from the command line". + +> Better: "Use Ctrl-C from the command line". + +- Subtle humor and puns about duckies are encouraged. + +## Writing command lines + +Use either "`laptop`" or "`duckiebot`" (not capitalized, as a hostname) as the prefix for the command line. + +For example, for a command that is supposed to run +on the laptop, use: + +> 
laptop $ cd ~/duckietown
+ +It will become: + + laptop $ cd ~/duckietown + +For a command that must run on the Duckiebot, use: + +> 
duckiebot $ cd ~/duckietown
+ +It will become: + + duckiebot $ cd ~/duckietown + +If the command is supposed to be run on both, omit the hostname: + + $ cd ~/duckietown + +## Frequently misspelled words + +- "Duckiebot" is always capitalized. + +- Use "Raspberry Pi", not "PI", "raspi", etc. + +- These are other words frequently misspelled: + + 5 GHz + WiFi + +## Other conventions + +When the user must edit a file, just say: "edit `/this/file`". + +Writing down the command line for editing, like the following: + + $ vi /this/file + +is too much detail. + +(If people need to be told how to edit a file, Duckietown is too advanced for them.) + +## Troubleshooting sections + +Write the documentation as if every step succeeds. + +Then, at the end, make a "Troubleshooting" section. + +Organize the troubleshooting section as a list of symptom/resolution. + +The following is an example of a troubleshooting section. + +### Troubleshooting + +Symptom: This strange thing happens. + +Resolution: Maybe the camera is not inserted correctly. Remove and reconnect. + +Symptom: This other strange thing happens. + +Resolution: Maybe the plumbus is not working correctly. Try reformatting the plumbus. diff --git a/docs/40_backend/00_part_backend.md b/docs/40_backend/00_part_backend.md new file mode 100644 index 0000000..145ccf4 --- /dev/null +++ b/docs/40_backend/00_part_backend.md @@ -0,0 +1,4 @@ +# Backend for `docs.duckietown.org` {#part:duckumentation-backend status=ready} + +This part describes the backend that allows the website to be published +at `docs.duckietown.org`. diff --git a/docs/40_backend/20_circle_ci.md b/docs/40_backend/20_circle_ci.md new file mode 100644 index 0000000..9afed1f --- /dev/null +++ b/docs/40_backend/20_circle_ci.md @@ -0,0 +1,3 @@ +# CircleCI integration {#duckumentation-circleci status=draft} + +TODO: Describe what is going on. diff --git a/docs/40_backend/69_compiling_pdf.md b/docs/40_backend/69_compiling_pdf.md new file mode 100644 index 0000000..feae1bb --- /dev/null +++ b/docs/40_backend/69_compiling_pdf.md @@ -0,0 +1,56 @@ +# \*Compiling the PDF version {#duckuments-pdf status=deprecated} + +Note: these are instructions that should not be needed anymore. + +This part describes how to compile the PDF version. + +Note: The dependencies below are harder to install. If you don't manage to do it, then you only lose the ability to compile the PDF. + +## Installing `nodejs` + +Ensure the latest version (>6) of `nodejs` is installed. + +Run: + + $ nodejs --version + 6.xx + +If the version is 4 or less, remove `nodejs`: + + $ sudo apt remove nodejs + +Install `nodejs` using [the instructions at this page][nodejs]. + +[nodejs]: https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions + +Next, install the necessary Javascript libraries using `npm`: + + $ cd $DUCKUMENTS + $ npm install MathJax-node jsdom@9.3 less + + +### Troubleshooting `nodejs` installation problems + +The only pain point in the installation procedure has been the installation of `nodejs` packages using `npm`. For some reason, they cannot be installed globally (`npm install -g`). + +Do **not** use `sudo` for installation. It will cause problems. + +If you use `sudo`, you probably have to delete a bunch of directories, +such as: `~/duckuments/node_modules`, `~/.npm`, and `~/.node_modules`, if they exist. + +## Installing Prince + +Install PrinceXML from [this page](https://www.princexml.com/download/). + +## Installing fonts + + +Copy the `~/duckuments/fonts` directory in `~/.fonts`: + + $ mkdir -p ~/.fonts # create if not exists + $ cp -R ~/duckuments/fonts ~/.fonts + +and then rebuild the font cache using: + + $ fc-cache -fv + diff --git a/docs/50_slides/00_part_slides.md b/docs/50_slides/00_part_slides.md new file mode 100644 index 0000000..4a20879 --- /dev/null +++ b/docs/50_slides/00_part_slides.md @@ -0,0 +1,5 @@ +# Slides {#part:slides status=ready} + +# Creating slides {#creating-slides status=ready} + +See this presentation: [](#making-slides) diff --git a/docs/50_slides/duckuments_slides.md b/docs/50_slides/duckuments_slides.md new file mode 100644 index 0000000..bad7b13 --- /dev/null +++ b/docs/50_slides/duckuments_slides.md @@ -0,0 +1,210 @@ +# Making slides {#making-slides type=slides status=ready nonumber=1 label-name="🎦 Making slides"} + +To create slides, use `type=slides` for an H1 header: + +```markdown +# Making slides {#making-slides type=slides status=ready nonumber=1} + +To create slides, use the attribute `type=slides` for an H1 header: + +``` + +## Next slides + + +Use second-level headers to make subsequent slides: + +```markdown +# Making slides {#making-slides type=slides status=beta} + + +To create slides, use `type=slides` for an H1 header: + +... + +## Next slides + +Use second-level headers to make subsequent slides: + + +``` + + +## Stepping + +Use the symbol `▶` to make the corresponding fragment appear on click. + + +```markdown + +* Step 1 ▶ +* Step 2 ▶ +* Step 3 ▶ + +``` + +* Step 1 ▶ +* Step 2 ▶ +* Step 3 ▶ + + +## Maths + +Latex still works here. + +A simple test for math: + +$$ +a + b \geq \sqrt{c} +$$ + +## Stepping through equations + +You can also step through equations: + +```markdown + +Consider: ▶ + +$$ +a = b ▶ +$$ + +Then we get: ▶ + +$$ +c = d ▶ +$$ +``` + +Consider: ▶ + +$$ +a = b ▶ +$$ + +Then we get: ▶ + +$$ +c = d ▶ +$$ + +Stepping through partial parts of equations is not supported. + + + +## Sub-slides + +You can have "sub slides" to make the presentation nonlinear. + +**Defining subslides**: Create a subslide by using header `h3`: + +```markdown +### Subslide 1 + +This is lower. + +### Subslide 2 + +This is even lower. +``` + +**Showing subslides**: Press down to show the subslides. + + +**Showing the slides map**: Press ESC again to look at the slides map. + + +### Subslide 1 + +This is lower. + +### Subslide 2 + +This is even lower. + +## Presentation mode + +Press the key S to enter presenters mode. + +Press ESC to exit presenter mode. + + +## Presenter notes + +Use a blockquote at the end of a slide to encode the presenter notes. + +```markdown +## Presenter notes + +Use a blockquote at the end of a slide to encode the presenter notes: + +> These are presenter notes that will appear in presenter mode. +``` + +> These are presenter notes that will appear in presenter mode. + +## Under the hood + +* All of this is built on top of `reveal.js`. + +* Please see [`reveal.js`](https://revealjs.com/) for the complete list of features. + +## Figures {#other-features} + +All other duckuments features work as expected. + +Example of a figure: + +
+ +
+ +```html +
+ +
+``` + +## Subfigures + +Subfigures with animation: + +
▶ +
Main caption
+
▶ +
Hello
+ +
+
▶ +
second
+ +
+
+ +```html +
▶ +
Main caption
+
▶ +
Hello
+ +
+
▶ +
second
+ +
+
+``` + + +## Cross references + +You can link to chapters and vice-versa: [](#creating-slides) + +```markdown +You can link to chapters and vice-versa: [](#creating-slides) +``` + +Link [to the previous slide](#other-features). + +## References diff --git a/docs/duckietown.css b/docs/duckietown.css new file mode 100644 index 0000000..9f5e65d --- /dev/null +++ b/docs/duckietown.css @@ -0,0 +1,115 @@ +/* Duckuments-specific CSS file */ + +p{ + margin-top: 1em; + margin-bottom: 0.5em; +} + +/* +body{ + padding-left: 0; +} + +section, p{ + max-width: 100%; +} + +section[status=beta], section[status=draft], section[status=unknown], +section[status=to-update], section[status=recently-updated], section[status=deprecated]{ + padding-right: 1em; +} + +#tocdiv{ + width: 30em; +} + +#tocdiv ul:first-child{ + padding: 10px; + border: 1px solid gray; + border-radius: 6px; + background-color: white; +} + +#not-toc{ + width: 520pt; + margin: auto; + font-size: 11pt; + padding: 20px; + margin-top: 1.4em; + border: 1px solid gray; + border-radius: 6px; + background-color: white; + transform: none; +} + +#not-toc section ul{ + text-indent: 11pt; +} + +#not-toc section .video-vimeo-player{ + width: 100%; + height: 18em; + margin-top: 1em; +} + +#tocdiv ul li{ + line-height: 1.5; +} + +#not-toc ul li{ + line-height: 1.4; +} + +#tocdiv > ul > li > ul{ + margin-left: 0.2em; + padding-left: 0.8em; + border-left: 3px solid lightgray; +} + +#tocdiv > ul > li > ul > li > ul{ + padding-left: 1.2em; +} + +#not-toc .github-etc-links{ + transform: scale(1.6); + outline: none; + border-radius: 4px; + background-color: #efeaea; + margin-right: 1em; + padding: 1.1pt 4pt 0.5pt 4pt; +} + +#not-toc .github-etc-links .github-edit-link{ + font-size: inherit; + color: black; +} + +#not-toc .github-etc-links .purl-link{ + font-size: 6pt; + margin: 0; + margin-left: 4pt; +} + +#not-toc h4{ + margin-top: 1.2em; +} + +#not-toc section > .navigation:first-child{ + margin-bottom: 2em; +} + +#not-toc section > .navigation:last-child{ + margin-top: 4em; +} +*/ + + +body:not(.show_todos) details.task, +body:not(.show_todos) details.error { + display: none; +} + +body.show_todos details.task, +body.show_todos details.error { + display: block; +} diff --git a/run-book-docker.sh b/run-book-docker.sh new file mode 100755 index 0000000..117ff29 --- /dev/null +++ b/run-book-docker.sh @@ -0,0 +1,89 @@ +#!/usr/bin/env bash +# language=sh +# set -euo pipefail +set -x # echo commands + +short=$1 +src=$2 + + + +if [ "$CI" = "" ] +then + branch=`git rev-parse --abbrev-ref HEAD` +else + branch=${CIRCLE_BRANCH} +fi + + +org=`git config --get remote.origin.url | cut -f2 -d":" | cut -f1 -d/ | tr '[:upper:]' '[:lower:]'` + +base=http://docs-branches.duckietown.org/${org}/duckuments/branch/${branch} +cross=${base}/all_crossref.html +permalink_prefix=${base}/${short}/out +extra_crossrefs=${base}/all_crossref.html + + +if [ "$CI" = "" ] +then + echo "Not on Circle, using parallel compilation." + cmd="rparmake n=4" + options1="--extra_crossrefs ${extra_crossrefs}" +else + echo "On Circle, not using parallel compilation to avoid running out of memory." + cmd=rmake + options1="" +fi + + + +dist=duckuments-dist + +if [ "$ONLY_FOR_REFS" = "" ] +then + options2="--output_file ${dist}/${short}/out.html --split ${dist}/${short}/out/" + +else + echo "Skipping polish, ONLY_FOR_REFS" + + # XXX: need to do split because of cross refs + options2="--split ${dist}/${short}/out/ --ignore_ref_errors --only_refs" +fi + +# only andrea and CI build the PDF version + +if [ "$USER" = "andrea" ] +then + options2="${options2} --pdf ${dist}/${short}/out.pdf" +fi + +if [ "$CI" = "" ] +then + echo +else + options2="${options2} --pdf ${dist}/${short}/out.pdf" +fi + + +mkdir -p ${dist} + +NP=${PWD}/node_modules:${NODE_PATH} + +#source deploy/bin/activate + +mcdp_render_manual="sudo docker run -v $PWD:/duckuments -e USER=$USER -e USERID=$UID -v $PWD:/home/$USER --user $UID andreacensi/mcdp_manual:1 mcdp-render-manual" + +DISABLE_CONTRACTS=1 NODE_PATH=${NP} ${mcdp_render_manual} \ + --src ${src} \ + --resources docs:${dist} \ + --stylesheet v_manual_split \ + --stylesheet_pdf v_manual_blurb_ready \ + --wordpress_integration \ + --output_crossref ${dist}/${short}/crossref.html \ + -o out/${short} \ + --permalink_prefix ${permalink_prefix} \ + ${options1} \ + ${options2} \ + -c "config echo 1; ${cmd}" + +# --symbols docs/symbols.tex \ diff --git a/run-book-native.sh b/run-book-native.sh new file mode 100755 index 0000000..bce771d --- /dev/null +++ b/run-book-native.sh @@ -0,0 +1,87 @@ +#!/usr/bin/env bash +# language=sh +# set -euo pipefail +# set -x # echo commands + +short=$1 +src=$2 + + + +if [ "$CI" = "" ] +then + branch=`git rev-parse --abbrev-ref HEAD` +else + branch=${CIRCLE_BRANCH} +fi + + +org=`git config --get remote.origin.url | cut -f2 -d":" | cut -f1 -d/ | tr '[:upper:]' '[:lower:]'` + +base=http://docs-branches.duckietown.org/${org}/duckuments/branch/${branch} +cross=${base}/all_crossref.html +permalink_prefix=${base}/${short}/out +extra_crossrefs=${base}/all_crossref.html + + +if [ "$CI" = "" ] +then + echo "Not on Circle, using parallel compilation." + cmd="rparmake n=4" + options1="--extra_crossrefs ${extra_crossrefs}" +else + echo "On Circle, not using parallel compilation to avoid running out of memory." + cmd=rmake + options1="" +fi + + + +dist=duckuments-dist + +if [ "$ONLY_FOR_REFS" = "" ] +then + options2="--output_file ${dist}/${short}/out.html --split ${dist}/${short}/out/" + +else + echo "Skipping polish, ONLY_FOR_REFS" + + # XXX: need to do split because of cross refs + options2="--split ${dist}/${short}/out/ --ignore_ref_errors --only_refs" +fi + +# only andrea and CI build the PDF version + +if [ "$USER" = "andrea" ] +then + options2="${options2} --pdf ${dist}/${short}/out.pdf" +fi + +if [ "$CI" = "" ] +then + echo +else + options2="${options2} --pdf ${dist}/${short}/out.pdf" +fi + + +mkdir -p ${dist} + +NP=${PWD}/node_modules:${NODE_PATH} + +#source deploy/bin/activate + +DISABLE_CONTRACTS=1 NODE_PATH=${NP} mcdp-render-manual \ + --src ${src} \ + --resources docs:${dist} \ + --stylesheet v_manual_split \ + --stylesheet_pdf v_manual_blurb_ready \ + --wordpress_integration \ + --output_crossref ${dist}/${short}/crossref.html \ + --likebtn 5ae54e0d6fd08bb24f3a7fa1 \ + -o out/${short} \ + --permalink_prefix ${permalink_prefix} \ + ${options1} \ + ${options2} \ + -c "config echo 1; ${cmd}" +# --symbols docs/symbols.tex \