diff --git a/.circleci/config.yml b/.circleci/config.yml index 6f88a91..f725120 100644 --- a/.circleci/config.yml +++ b/.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 diff --git a/.gitignore b/.gitignore index dd5f66e..83321f6 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ out duckuments-dist .DS_Store node_modules +.idea diff --git a/.gitmodules b/.gitmodules index 81c92cd..7109785 100644 --- a/.gitmodules +++ b/.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 diff --git a/Makefile b/Makefile index 2ab4e5b..f2ff563 100644 --- a/Makefile +++ b/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 diff --git a/README.md b/README.md index 223960e..7ea7917 100644 --- a/README.md +++ b/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 \ No newline at end of file diff --git a/book/duckumentation/10_contributing/10_intro.md b/book/duckumentation/10_contributing/10_intro.md index cd4b7cf..bfdca2c 100644 --- a/book/duckumentation/10_contributing/10_intro.md +++ b/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). diff --git a/book/duckumentation/10_contributing/40_simple_way.md b/book/duckumentation/10_contributing/40_simple_way.md new file mode 100644 index 0000000..85e4207 --- /dev/null +++ b/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 + + diff --git a/book/duckumentation/10_contributing/41_workflow.md b/book/duckumentation/10_contributing/41_workflow.md new file mode 100644 index 0000000..c4f61ec --- /dev/null +++ b/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. + +
+ +
+ +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. + +
+ +
+ + +## 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/book/duckumentation/10_contributing/58_markdown_editors.md b/book/duckumentation/10_contributing/50_markdown_editors.md similarity index 84% rename from book/duckumentation/10_contributing/58_markdown_editors.md rename to book/duckumentation/10_contributing/50_markdown_editors.md index be8167f..dd58ae0 100644 --- a/book/duckumentation/10_contributing/58_markdown_editors.md +++ b/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) diff --git a/book/duckumentation/10_contributing/55_installation.md b/book/duckumentation/10_contributing/55_installation.md index 0a64cf0..4ca0619 100644 --- a/book/duckumentation/10_contributing/55_installation.md +++ b/book/duckumentation/10_contributing/55_installation.md @@ -1,18 +1,14 @@ -# Installation and compilation {#duckumentation-installing-docs-system status=ready} +# Experts: Compiling all books {#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. +This section describes how to compile all books at the same time. -See: [Basic SSH config](#ssh-local-configuration). +## Setup -See: [Key pair creation](#howto-create-key-pair). +### Fork the `duckuments` repo -See: [Adding public key on Github](#howto-add-pubkey-to-github). - -### Download the `duckuments` repo +In the following, we are going to assume that the documentation system is installed in `~/duckuments`. However, it can be installed anywhere. -Download the `duckietown/duckuments` repository in the `~/duckuments` directory: +Fork the `duckietown/duckuments` repository in the `~/duckuments` directory: ``` $ git clone --depth 11 git@github.com:duckietown/duckuments ~/duckuments @@ -21,12 +17,9 @@ $ 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. + + ## Compiling the documentation {#compiling-master} @@ -46,7 +41,7 @@ For other distributions, you might need to modify the `install-ubuntu16` Makefil To compile everything from scratch, run: ``` -$ make realclean all +$ make realclean all -j ``` To see the results, open the file @@ -58,7 +53,7 @@ To see the results, open the file If you want to do incremental compilation, you can omit the `clean` and just use: ``` -$ make all +$ make all -j ``` ### Compiling a single book @@ -68,10 +63,9 @@ After you have compiled all the books, you can use one of the following command ``` $ make book-duckumentation $ make book-the_duckietown_project -$ make book-opmanual_duckiebot_base -$ make book-opmanual_duckiebot_fancy +$ make book-opmanual_duckiebot $ make book-opmanual_duckietown -$ make book-software_carpentry +$ make book-software_reference $ make book-software_devel $ make book-software_architecture $ make book-class_fall2017 @@ -90,21 +84,94 @@ The compilation is always incremental, but sometimes you might need to do a rese $ make realclean ``` -## Reporting problems +## Editing the books -First, see the section [](#markduck-troubleshooting) for common problems and their resolution. +The books sources are in `docs/docs-![book]`. -Please report problems with the duckuments using [the `duckuments` issue tracker][tracker]. +Each of those are a submodule. -[tracker]: https://github.com/duckietown/duckuments/issues +To edit, do the following. -Special notes: +Fork the `docs-![book]` repository that you wish to edit. -* 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: +For example, for `docs-exercises`, it looks like this: -``` -$ git -C ~/duckuments rev-parse HEAD # commit for duckuments -$ git -C ~/duckuments/mcdp rev-parse HEAD # commit for mcdp -``` + $ cd ~/duckuments/docs/docs-exercises + $ hub fork + Updating ![username] + From ssh://github.com/duckietown/docs-exercises + * [new branch] master -> ![username]/master + new remote: ![username] + +The command has forked the repository. + +It also created a new Git remote called `![username]`: + + $ git remote -v + ![username] git@github.com:![username]/docs-exercises.git (fetch) + ![username] git@github.com:![username]/docs-exercises.git (push) + origin git@github.com:duckietown/docs-exercises.git (fetch) + origin git@github.com:duckietown/docs-exercises.git (push) + +Tell Git that you want to push to your fork: + + $ git branch --set-upstream-to ![username]/master + +Now, when you push you will push to your fork: + + $ git push + +To create a pull request, use: + + $ hub pull-request + https://github.com/duckietown/docs-exercises/pull/![id] + +Visit the URL to check your pull request. + + +## Editing the book collection + +Once you have changed your changes to the books, you need to do a pull-request for the `duckuments` repo. + + +### Forking + +As before, make sure you are on your fork: + + $ cd ~/duckuments/ + $ hub fork + Updating ![username] + From ssh://github.com/duckietown/duckuments + * [new branch] master -> ![username]/master + new remote: ![username] + $ git branch --set-upstream-to ![username]/master + + +### Updating + +For this you need to be able to know how to use submodules. + +If you go to `~/duckuments`, the status will appear like this: + + $ git status + On branch master + Your branch is up-to-date with 'origin/master'. + + Changes not staged for commit: + (use "git add ..." to update what will be committed) + (use "git checkout -- ..." to discard changes in working directory) + (commit or discard the untracked or modified content in submodules) + + modified: docs/docs-exercises (new commits) + +This means that you have changes in the submodules that you need to commit. + +Just like with files, you can use `git commit` to do so: + + $ git commit -a -m "Update of repository" + $ git push + +Now create the pull request using: + + $ hub pull-request + diff --git a/book/duckumentation/10_contributing/57_workflow.md b/book/duckumentation/10_contributing/57_workflow.md deleted file mode 100644 index b41d935..0000000 --- a/book/duckumentation/10_contributing/57_workflow.md +++ /dev/null @@ -1,96 +0,0 @@ -# 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/book/duckumentation/20_markduck/68_advanced_guide.md b/book/duckumentation/20_markduck/68_advanced_guide.md index ef6529c..afaa4db 100644 --- a/book/duckumentation/20_markduck/68_advanced_guide.md +++ b/book/duckumentation/20_markduck/68_advanced_guide.md @@ -14,17 +14,17 @@ This is the syntax: For example, this code: -
+
Cool Duckietown by night
-
+ produces this result: -
-
Cool Duckietown by night
- -
+
+
Cool Duckietown by night
+ +
diff --git a/book/duckumentation/50_slides/duckuments_slides.md b/book/duckumentation/50_slides/duckuments_slides.md index bad7b13..6958706 100644 --- a/book/duckumentation/50_slides/duckuments_slides.md +++ b/book/duckumentation/50_slides/duckuments_slides.md @@ -1,4 +1,4 @@ -# Making slides {#making-slides type=slides status=ready nonumber=1 label-name="🎦 Making slides"} +# Making slides {#making-slides type=slides status=ready nonumber=1} To create slides, use `type=slides` for an H1 header: diff --git a/resources b/resources index 775dafa..e91b51e 160000 --- a/resources +++ b/resources @@ -1 +1 @@ -Subproject commit 775dafa31aa57909cf1c9fb80ef630c00c2557b7 +Subproject commit e91b51e59923899bcc1cfa42290ddd93d8e25d5d