README.rst 1.86 KB
Newer Older
1 2 3
===========
Mock Turtle
===========
4

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

8 9
Documentation Build Instructions
================================
10

11 12 13
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/``.
14

15 16 17 18
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.
19

20 21 22
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:::
23

24 25 26 27 28 29
  sudo apt install virtualenv
  cd doc
  virtualenv build_env
  . build_env/bin/activate
  pip install -r requirements.txt
  deactivate
30

31 32 33
**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.
34

35 36
Once the environment is installed, you can (re)build the documentation by
doing:::
37

38 39 40 41
  cd doc
  . build_env/bin/activate
  make html
  deactivate
42

43 44
The generated documentation can be accessed by opening
``doc/_build/html/index.html`` in your browser.
45

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

49 50 51 52
  cd doc
  . build_env/bin/activate
  make latexpdf
  deactivate
53

54 55
The generated documentation can be accessed by opening the PDF found under
``doc/_build/latex/``.
56

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