Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
94 lines (69 sloc) 4.97 KB

Documentation of JuPedSim

This directory contains the documentation files for JuPedSim.

The project documentation is published as a GitHub page, which is rendered using jekyll and the Jekyll Documentation Theme.

File structure

Aside from some files needed by the theme the most important directories are organized as follows:

  • doxygen: This directory will be populated (automatically) by the html files generated by an eventual make doc.
  • pages: Here the markdown files used in the documentation are organized contentwise as follows:
    • jupedsim
    • jpscore
    • jpsreport
    • jpsvis
    • jpseditor

While the directory jupedsim contains general documentation related to the whole project like for example installation instructions or publications, the other jps* directories contain specific documentation related to the different sub-projects.

In the directory projects several projects, using or developing JuPedSim are mentioned.

The new theme comes with a handy option: tags.

Pages can be sorted and grouped by tag. The following tags are implemented (see _data/tags):

  • jpscore: subject related to jpscore.
  • jpsreport: subject related to jpsreport.
  • model: documentation related to modeling in general.
  • test: documentation of tests.
  • file: documentation of input and output files.
  • measurement: documentation of the measurement methods.
  • jpsreport_tutorial: practical tutorials showcasing jpsreport use
  • jpscore_tutorial practical tutorials showcasing jpscore use
  • simulation: documentation of simulation-related features
  • getting_started: help users to get-started, e.g. howtos
  • troubleshooting: installation, issues-related documentation
  • removed: removed features, that are planned to make a come back

Note: Every tag has a correspending html-file in pages/tags.

How to use this documentation actively

  • Choose the right directory: In order to edit, correct or produce new documentation, the directories pages/jupedsim and pages/jps* should be used. The name of your new page should be prefixed accordingly. For example, you want to document a new/old feature in jpscore called desired speed. Then the new page should be named jpscore_desired_speed.md and stored in the directory pages/jpscore.

  • Edit the sidebar: If the page is new, it should be placed at the right position in the sidebar. For this purpose edit the file _data/sidebars/jupedsim_sidebar.yml.

  • Images should be saved in the directory images and linked using the markdown syntax. For example: ![The main components defining a geometry]({{ site.baseurl }}/images/class-diagram.png). Here two important things are to be considered:

    • Use of the variable site.baseurl. The pages are rendered by GitHub, therefore using absolute paths is not a good idea and won't render the page properly.
    • The description between the squared brackets is the caption of the image. It's nice to have. Please use meaningful captions.

    Bear in mind that by using the markdown syntax, it is not possible to define the size of the images, therefore you may have to resize the images before using them.

  • Use appropriate frontmatter. See this page for more information. Especially, tags, last_updated and summary are helpful and would be nice to use. For drafted but not-to-be-published pages use published: false.

Producing a pdf file of the documentation

The documentation using markdown can be rendered using GitHub pages. Moreover, the same md-files can also be used to produce a pdf-file.

The directory jps_guide contains the files necessary to make this happen. It contains the following files:

  • JuPedSim.tex: This is the "master TeX-file". It defines the structure of the guide (chapters, sections, ...).
  • Makefile: Makefile to make the latex files.
  • make_guide.py: This script does the main work and triggers the whole markdown -> latex -> pdf magic. Especially it does the following:
    • Creates a directory called _tex
    • Converts pages/*.md to _tex/\*.tex
    • Copies the file post-checkout in ../../.git/hooks/post-checkout. After calling git checkout a titlepage.tex is created containing the front page of the guide with useful git information.
    • Calls make, which creates the pdf file.
    • Finally, it calls make clean and deletes unnecessary files.
  • post-checkout: necessary to create titlepage.tex.

Note: This script depends on kramdown.

Publications

The list of publications is automatically generated based on a Zotero collection by BitBase.

Check the changes before pushing to GitHub

Run locally jekyll and check if your changes render properly:

jekyll serve

{%include note.html content="run the from within docs/."%}

You can’t perform that action at this time.