-
Notifications
You must be signed in to change notification settings - Fork 6
/
Copy pathREADME
41 lines (36 loc) · 2.02 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
This directory contains documentation files (*.rst) and sphinx utilities to
build them into webpages, latex, and text files.
At the moment, in order to view them in a pretty and composed fashion you will
need to build them yourself. This will change once we have stabilized the
documentation such that we can share them.
1) Obtain sphinx - https://www.sphinx-doc.org
* What is sphinx? It is a python package that helps you produce nice
looking documentation in various forms, so you can write the
documentation once, then use sphinx to generate html, latex (pdf),
text, or many other forms.
* What do I need to install sphinx? You will need Python
(http://www.python.org/), and sphinx.
2) Build the documentation
* Choose a desired output format (html, latex, text).
* type: make <format>
* For example, "make html" will produce webpages containing documentation
and APIs for the framework code.
* The documentation in the specified format will be located in:
doc/_build/<format>/
For example, "make html" puts the top-level page:
doc/_build/html/index.html
3) Writing documentation
* Each category of documentation (e.g., user guides, component guides)
contains its own document that explains the category and the documents
contained therein. These documents must be added to the "toc-tree" in
the category description document in order to be discovered and built by
Sphinx. If the category has only one document, it does not need a
toc-tree, it should, however, be included in the top-level toc-tree in
index.rst.
* Documentation is written using the reStructuredText markup language. It
is similar to languages used to write wiki documents. You can find a
good reference at https://www.sphinx-doc.org, which covers the
basics, and links to more detailed information on the language.
* Documentation files must end in .rst.
* Docstrings in the source code for the framework use reStructuredText
formatting as well.