|
1 | | -To be implemented |
| 1 | +## About magPyLib Documentation |
| 2 | + |
| 3 | +- Documentation is done with [Sphinx](http://www.sphinx-doc.org/en/master/) v1.8.2. |
| 4 | +- Sphinx configuration is [conf.py](./conf.py); |
| 5 | +- Docstring format is under the [Numpy Convention](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html). |
| 6 | +- Sphinx is configured to read Docstring information from the codebase and convert it into pages utilizing the [autodoc extension](http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html). |
| 7 | + |
| 8 | + - These generated files are created at build time and put into a folder called `_autogen` |
| 9 | + |
| 10 | +- Handwritten document pages and guides are kept in the [_pages](./_pages) folder. |
| 11 | + - They use a combination of [Markdown](https://commonmark.org/help/) and [restructuredText](http://docutils.sourceforge.net/docs/ref/rst/directives.html), utilizing [recommonmark](https://github.com/rtfd/recommonmark) as interface. |
| 12 | + - These documents are converted to `.html` files by Sphinx during build time. |
| 13 | + |
| 14 | +- Example code with visual output **generated during build time** are kept in the [pyplots](./pyplots) folder. |
| 15 | + - This utilizes the Matplotlib's [plot directive for restructuredText](https://matplotlib.org/devel/plot_directive.html), placing the code and its graphical output when it is referenced within the directive in the documentation pages. |
| 16 | + |
| 17 | +- Images, web code and videos are kept in the [_static](./_static) folder. |
| 18 | + |
| 19 | +--- |
| 20 | + |
| 21 | +### Building Locally |
| 22 | + |
| 23 | +This repository is set up to be easily built on [ReadTheDocs](https://readthedocs.org/) as the codebase is updated. |
| 24 | + |
| 25 | +##### To build locally on Linux, |
| 26 | + |
| 27 | +1. [Install Sphinx](http://www.sphinx-doc.org/en/master/usage/installation.html) |
| 28 | +2. Install the dependencies on [requirements.txt](./requirements.txt): |
| 29 | + ``` |
| 30 | + pip install requirements.txt |
| 31 | + ``` |
| 32 | +
|
| 33 | +
|
| 34 | +3. Run [make](http://man7.org/linux/man-pages/man1/make.1.html) to build the documentation: |
| 35 | +
|
| 36 | + ```bash |
| 37 | +
|
| 38 | + make html |
| 39 | + ``` |
| 40 | +
|
| 41 | +This will create a `_build` folder with an `index.html`, containing the built documentation webpage structure. |
| 42 | +
|
| 43 | +--- |
| 44 | +
|
| 45 | +##### To build locally on Windows, |
| 46 | +
|
| 47 | +1. [Install Sphinx](http://www.sphinx-doc.org/en/master/usage/installation.html) |
| 48 | +2. Install the dependencies on [requirements.txt](./requirements.txt): |
| 49 | + ``` |
| 50 | + pip install -r requirements.txt |
| 51 | + ``` |
| 52 | +
|
| 53 | +3. Build the documentation with the `.bat` script: |
| 54 | +
|
| 55 | + ```bash |
| 56 | +
|
| 57 | + make.bat html |
| 58 | + ``` |
| 59 | +
|
0 commit comments