README.rst 1.93 KB
Newer Older
Federico Vaga's avatar
Federico Vaga committed
1 2 3 4 5
..
  SPDX-License-Identifier: CC-BY-SA-4.0

  SPDX-FileCopyrightText: 2019 CERN

6 7 8
===========
Mock Turtle
===========
9

10
Mock Turtle is a framework to develop embedded systems on FPGA.
11
For more information, please read the documentation in ``doc/``.
12

13 14
Documentation Build Instructions
================================
15

16 17 18
This project uses `Sphinx <http://www.sphinx-doc.org/en/master/>`_ to generate
documentation from `reStructuredText <http://docutils.sourceforge.net/rst.html>`_
and `CommonMark <https://commonmark.org/>`_ (Markdown) files under ``doc/``.
19

20 21 22 23
To build the documentation, it is highly recommended to setup a
`Python virtual environment <https://virtualenv.pypa.io/en/stable/>`_ where
the necessary packages (docuilts, sphinx, etc.) can be installed via
`pip <https://pypi.org/project/pip/>`_ and be kept at a specific version.
24

25 26 27
The following steps illustrate how to do this on a Debian/Ubuntu Linux box,
with the virtual environment placed inside the ``doc/`` folder of the project
itself:::
28

29 30 31 32 33 34
  sudo apt install virtualenv
  cd doc
  virtualenv build_env
  . build_env/bin/activate
  pip install -r requirements.txt
  deactivate
35

36 37 38
**Note:** If you use the same folder name and location (``doc/build_env``) for
the virtual environment as in the above example, there is already a gitignore
rule in place that will not track any auto-generated files within that folder.
39

40 41
Once the environment is installed, you can (re)build the documentation by
doing:::
42

43 44 45 46
  cd doc
  . build_env/bin/activate
  make html
  deactivate
47

48 49
The generated documentation can be accessed by opening
``doc/_build/html/index.html`` in your browser.
50

51 52
Alternatively, if you have `LaTeX <https://www.latex-project.org/>`_ installed,
you can produce a PDF by doing:::
53

54 55 56 57
  cd doc
  . build_env/bin/activate
  make latexpdf
  deactivate
58

59 60
The generated documentation can be accessed by opening the PDF found under
``doc/_build/latex/``.
61

62
**Note:** Only HTML and PDF outputs from Sphinx are supported and tested.