===================================================== Getting a RTD Started for Git Repo ===================================================== The following is a minimalist guide to getting a Readthedocs page. Most of your documentation should be in ``.rst`` documents, where this guide will show how to add figures, math, and code blocks. .. note:: I'm a rookie at RTD, and willing to learn. Happily accepting all constructive criticisms on how to make things better! Your Code Documentation -------------------------- Your documentation blocks should also follow the ``.rst``, here are some examples for ``Python`` objects and functions. For purposes of the tutorial, let ``core.py`` be the following: .. code-block:: python MyClass: """ Description ----------- Class that has attributes and methods. Attributes ----------- name : str Name of the concerning party. value : int Value of the transaction. Methods ------- __init__(self,name,value) Initializes the class object. mymethod(self,x) Multiplies the argument x by 10. """ def __init__(self,name,value): self.name = name self.value = value def mymethod(self,x): """ Description ----------- Multiplies x by 10. Parameters ----------- x : float Quantity to multiply by 10. Returns ------- float The quantity x multiplied by 10. """ return 10 * x def myfunc(y): """ Description ----------- Adds 5 to y Parameters ---------- y : float or int Quantity to add 5. Returns ------- int or float The quantity y plus 5. """ return y + 5 The Repository and Configuration --------------------------------------- First, Structure your repository according to the following structure: - main - myreponame - myreponame - core.py - util.py - docs - media - landing_page_image.png - tests - ... - README.md Your source code for the package your making documentation for should be in the ``main/myreponame/myreponame`` directory. Go ahead and fire up a command prompt or terminal. From your ``/myreponame`` directory, .. code-block:: console pip install sphinx cd docs sphinx-quickstart This will create a ``conf.py`` file and ``index.rst``. My default configuration for the ``conf.py`` is shown below .. code-block:: python # Configuration file for the Sphinx documentation builder. # # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information import sys import os sys.path.insert(0, os.path.abspath('../myreponame')) sys.path.insert(0, os.path.abspath('../..')) sys.path.insert(0, os.path.abspath('..')) sys.path.insert(0, os.path.abspath('.')) project = 'myreponame' copyright = '2024, My Institution or Organization' author = 'First Last, First Last, First Last' #If multiple Authors release = '0.0' # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration # You may add other extensions to this list as required. extensions = [ 'sphinx.ext.duration', 'sphinx.ext.doctest', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.intersphinx', 'sphinx.ext.mathjax' ] templates_path = ['_templates'] exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_theme = 'alabaster' html_static_path = ['_static'] html_logo = 'media/gtlogo.png' # Common modules that used, add more as necessary. autodoc_mock_imports = ['numpy', 'scipy', 'matplotlib'] For purposes of this tutorial, I recommend replacing the content of the autogenerated ``conf.py`` with the above. .. note:: If you use any packages within your code modules, i.e., ``core.py``, they must be added to the ``autodoc_mock_imports`` or the readthedocs build will fail. Ensure you change the ``myreponame`` to yours. A typical configuration for my ``index.rst`` is as follows: .. code-block:: rst Welcome to the documentation for myreponame ============================================ .. image:: media/landing_page_image.png **myreponame** is a Python library intended to do stuff. Check out the :doc:`setup_and_installation` section for further information, including how to install the project. .. note:: This project is under active development. Contents -------- .. toctree:: :maxdepth: 2 :caption: Getting Started setup_and_installation .. toctree:: :maxdepth: 2 :caption: Functional Blocks functional_blocks .. toctree:: :maxdepth: 2 :caption: Tutorials: tutorials/firsttutorial tutorials/secondtutorial The files ``setup_and_installation.rst``, ``functional_blocks``, and the ones within the ``tutorial`` directory are *user-created* and fairly standard components of the documentation. For example ``setup_and_installation.rst``, .. code-block:: rst Installation ============= .. _installation: To use radar, first install it using pip (Same for Windows and Linux): .. code-block:: console git clone https://github.com/username/myreponame.git cd myreponame (.venv) $ pip install ./ and ``functional_blocks.rst``, I'll use something like the following to list out all documentation for objects and functions within my code. For example, my project might have two modules ``util.py`` and ``core.py``, see the project structure from earlier for their location. ``core.py`` was described explicitly here, do not feel compelled to create filler documentation ``util.py``, just creating the file is sufficient. The ``automodule`` block will parse the ``"""`` documentation blocked sections and build an html page based on that ``.rst`` within the documentation block. This doesn't always work perfectly, and may require some configuring. .. code-block:: rst myreponame.util =========== \..\ automodule:: myreponame.util :members: :undoc-members: :exclude-members: __dict__, __weakref__, __module__ myreponame.core =========== \..\ automodule:: myreponame.core :members: :undoc-members: :exclude-members: __dict__, __weakref__, __module__ .. note:: The proper syntax is actually ``.. automodule::``, but needs to be this way to work as non-executable ``.rst`` here. Building the Project --------------------------------------- Go ahead and create a ``tutorials`` directory and provide two ``.rst`` files within ``firsttutorial`` and ``secondtutorial``. You may add to these later, but just so they fit the template outline before. At this point you can do an intial build from the ``myreponame/docs`` folder .. code-block:: console make html If successful, this will create a folder ``_build``. You can you the resultant documentation page ``_build/html/index.html``. Feel free to explore this a little bit to get a feel for how the ``.rst`` files produce the project structure. You can add more to your ``tutorial`` directory files to experiment with math or other markup: .. code-block:: rst .. math:: f_1(\alpha) + g_2(\beta) = 1 Hosting on Readthedocs --------------------------------------- 1. Create a readthedocs account https://about.readthedocs.com/ and link your ``Git`` account. This did not work with Georgia Tech's LDAP Git... 2. Add a ``requirements.txt`` file in ``main/myreponame/docs``. It can be barebones as literally one word, but you need this nonetheless. ..code-block:: sphinx 3. Add file within the ``main/myreponame`` level of your project, ``.readthedocs.yaml`` .. code-block:: yaml version: "2" build: os: "ubuntu-22.04" tools: python: "3.10" python: install: - requirements: docs/requirements.txt sphinx: configuration: docs/conf.py 4. Go to ``builds`` under that project and click ``build version``. If all goes well you should be able to ``View Docs``. If you see something no quite right with your page but go no error, check the raw build log back on the ``builds`` page.