Joshy 1 year ago
parent
commit
a89161e80f
2 changed files with 98 additions and 0 deletions
  1. BIN
      82eec4a9e64f6a8977ba5e38d7a30c30.png
  2. +98
    -0
      README.md

BIN
82eec4a9e64f6a8977ba5e38d7a30c30.png View File

Before After
Width: 1100  |  Height: 939  |  Size: 166KB

+ 98
- 0
README.md View File

@@ -0,0 +1,98 @@
# **DERO documentation (docs.dero.io)**

![DERO Docs Site](https://git.dero.io/joshy/DERO_Docs_Site/src/branch/master/82eec4a9e64f6a8977ba5e38d7a30c30.png)


This repository contains the source files of DERO's documentation, in reStructuredText markup language (reST).

They are meant to be parsed with the [Sphinx](https://www.sphinx-doc.org/) documentation builder to build the HTML documentation on [DERO's website](http://DERO.io).

**Theming**

The DERO documentation uses the default sphinx_rtd_theme with many customizations applied on top.

**Editing existing pages**

To edit an existing page, locate its .rst source file and open it in your favorite text editor. You can then commit the changes, push them to your fork and make a pull request. Note that the pages in classes/ should not be edited here, they are automatically generated from DERO's XML class references. See Contribute to the Class Reference for details.

**Adding new pages**

To add a new page, create a .rst file with a meaningful name in the section you want to add a file to, e.g. tutorials/3d/light_baking.rst. Write its content like you would do for any other file, and make sure to define a reference name for Sphinx at the beginning of the file (check other files for the syntax), based on the file name with a "doc_" prefix (e.g. .. _doc_light_baking:).

You should then add your page to the relevant "toctree" (table of contents, e.g. basic_mining.rst). By convention, the files used to define the various levels of toctree are prefixed with an underscore, so in the above example the file should be referenced in rtd_pages/basic_mining.rst. Add your new filename to the list on a new line, using a relative path and no extension, e.g. here light_baking.

**Sphinx and reStructuredText syntax**

Check Sphinx's [reST Primer](https://www.sphinx-doc.org/en/stable/rest.html) and the [official reference](http://docutils.sourceforge.net/rst.html) for details on the syntax.

Sphinx uses specific reST comments to do specific operations, like defining the table of contents (:toctree:) or cross-referencing pages. Check the [official Sphinx documentation](http://https://www.sphinx-doc.org/en/stable/index.html) for more details, or see how things are done in existing pages and adapt it to your needs.

**Adding images and attachments**

To add images, please put them in an img/ folder next to the .rst file with a meaningful name and include them in your page with:

`.. image:: img/image_name.png`

Similarly, you can include attachments (like assets as support material for a tutorial) by placing them into a files/ folder next to the .rst file, and using this inline markup:

`:download:`myfilename.zip <files/myfilename.zip>``

**Building with Sphinx**

To build the HTML website (or any other format supported by Sphinx, like PDF, EPUB or LaTeX), you need to install [Sphinx](https://www.sphinx-doc.org/) >= 1.3 as well as (for the HTML) the [readthedocs.org theme](https://github.com/snide/sphinx_rtd_theme). You also need to install the Sphinx extensions defined in `requirements.txt.`

Those tools are best installed using [pip](https://pip.pypa.io/), Python's module installer. The Python 3 version might be provided (on Linux distros) as `pip3` or `python3-pip`. You can then run:

`pip install -r requirements.txt`

You can then build the HTML documentation from the root folder of this repository with:

`make html`

or:

`make SPHINXBUILD=~/.local/bin/sphinx-build html`

```
# On Linux/macOS
make html SPHINXOPTS=-j2

# On Windows
set SPHINXOPTS=-j2 && make html
```

The compilation might take some time as the `classes/` folder contains many files to parse.

In case of a `MemoryError` or `EOFError`, you can remove the `classes/` folder and run `make` again. This will drop the class references from the final HTML documentation but will keep the rest intact. Make sure to avoid using `git add` . in this case when working on a pull request, or the whole `classes/` folder will be removed when you make a commit.

You can then test the changes live by opening `_build/html/index.html` in your favorite browser.

**Building with Sphinx on Windows**

On Windows, you need to:

* Download the Python installer here.
* Install Python. Don't forget to check the "Add Python to PATH" box.
* Use the above pip commands.
*
Building is still done at the root folder of this repository using the provided `make.bat`:

`make.bat html`

Alternatively, you can build with this command instead:

`sphinx-build -b html ./ _build`

Note that during the first build, various installation prompts may appear and ask to install LaTeX plugins. Make sure you don't miss them, especially if they open behind other windows, else the build may appear to hang until you confirm these prompts.

You could also install a normal `make` toolchain (for example via MinGW) and build the docs using the normal `make html`.

**Building with Sphinx and virtualenv**

If you want your Sphinx installation scoped to the project, you can install it using virtualenv. Execute this from the root folder of this repository:

`virtualenv --system-site-packages env/
. env/bin/activate
pip install -r requirements.txt`

Then do `make html` like above.

Loading…
Cancel
Save