README.md

About magPyLib Documentation

• Documentation is done with Sphinx v1.8.2.

• Sphinx configuration is conf.py;

• Docstring format is under the Numpy Convention.

• Sphinx is configured to read Docstring information from the codebase and convert it into pages utilizing the autodoc extension.

  • These generated files are created at build time and put into a folder called _autogen

• Handwritten document pages and guides are kept in the _pages folder.

  • They use a combination of Markdown and restructuredText, utilizing recommonmark as interface.
  • These documents are converted to .html files by Sphinx during build time.

• Example code with visual output generated during build time are kept in the pyplots folder.

  • This utilizes the Matplotlib's plot directive for restructuredText, placing the code and its graphical output when it is referenced within the directive in the documentation pages.

• Images, web code and videos are kept in the _static folder.

---

Building Locally

This repository is set up to be easily built on ReadTheDocs as the codebase is updated.

To build locally on Linux,

1. Install Sphinx

2. Install the dependencies on requirements.txt:

   pip install requirements.txt
   

3. Run make to build the documentation:

   make html

This will create a _build folder with an index.html, containing the built documentation webpage structure.

---

To build locally on Windows,

1. Install Sphinx

2. Install the dependencies on requirements.txt:

   pip install -r requirements.txt
   

3. Build the documentation with the .bat script:

   make.bat html