Add documentation subpage.

Author: ebezzam

.readthedocs.yaml

@@ -0,0 +1,25 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/source/conf.py
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+# formats:
+#    - pdf
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - requirements: docs/requirements.txt

README.rst

@@ -90,70 +90,6 @@ To run a specific test:
     (project_env) pytest tests/test_fftconvolve.py::test_fft
 
 
-Documentation
-=============
-
-Will be using `Sphinx <https://www.sphinx-doc.org/en/master/>`__ to generate documentation.
-
-#. Write docstrings when coding. Great if already started!
-
-First time only steps
-#. (Recommended) create a lightweight virtual environment for building the documentation. Can save a lot of time when building docs remotely, as we'll show with ReadTheDocs
-
-.. code:: bash
-    
-    # create new environment, press enter to accept
-    conda create -n docs_env python=3.9
-
-    # activate environment
-    conda activate docs_env
-
-    # install requirements
-    (docs_env) pip install -e .
-    (docs_env) cd docs
-    (docs_env) pip install -r requirements.txt
-
-#. Use ``sphinx-quickstart`` (first-time only!). Do separate source and build. Enter project details through terminal.
-
-Otherwise
-
-#. Fill in index and create other files. Edit conf, like adding mock docs.
-#. Build docs with e.g. ``make html``.
-#. open ``docs/build/html/index.html`` in browser.
-#. host on `ReadTheDocs <https://readthedocs.org/>`__ or GitHub pages.
-
-
-Some documentation tips
------------------------
-
-- take a look at our conf.py which we've modified from the generated one
-- ex: changing theme to RTD
-- intersphinx mapping to connect to other docs
-- mock imports
-
-.. code:: bash
-    
-    # create new environment, press enter to accept
-    conda create -n docs_env python=3.9
-
-    # activate environment
-    conda activate docs_env
-
-    # install requirements
-    (docs_env) pip install -r docs/requirements.txt
-
-#. Will be using `Sphinx <https://www.sphinx-doc.org/en/master/>`__ to generate documentation. This requires 
-
-.. code:: bash
-
-    # build docs
-    (docs_env) python setup.py build_sphinx
-
-    
-
-#. Use `Sphinx <https://www.sphinx-doc.org/en/master/>`__ to generate documentation.
-
-
 Releasing new version and deploying to PyPi
 ===========================================
 
@@ -200,5 +136,4 @@ TODO
 - example file with hydra
 - manifest file to not include file in package
 - GitHub actions for releasing to PyPi when changes to version
-- documentation (autodoc)
 - adding badges to README

docs/source/conf.py

@@ -21,7 +21,7 @@
 
 sys.path.insert(0, os.path.abspath(os.path.join("..", "..")))
 
-MOCK_MODULES = ["matplotlib", "matplotlib.pyplot", "numpy", ""]
+MOCK_MODULES = ["matplotlib", "matplotlib.pyplot", "numpy"]
 for mod_name in MOCK_MODULES:
     sys.modules[mod_name] = mock.Mock()
 
@@ -77,4 +77,4 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+# html_static_path = ["_static"]

docs/source/documentation.rst

@@ -0,0 +1,153 @@
+Documentation
+=============
+
+We will be using a `Sphinx <https://www.sphinx-doc.org/en/master/>`__ to generate documentation from 
+docstrings that are written within code. Docstrings are long-form
+comments beneath class and functions declaration that typically describe:
+
+- What the function or class does.
+- Its inputs and their data types.
+- Its outputs and their data types.
+
+For example:
+
+.. code:: Python
+
+    def add(a, b):
+        """
+        Add two integers.
+        
+        Parameters
+        ----------
+        a : int
+            First integer.
+        b : int
+            Second integer.
+
+        Returns
+        -------
+        result : int
+            Sum of inputs.
+
+        """
+
+        assert isinstance(a, int)
+        assert isinstance(b, int)
+        return a + b
+
+Which will be rendered as :func:`pydevtips.utils.add`.
+
+Initial setup
+-------------
+
+So you've diligently written your docstrings (or used GitHub Copilot!), and you 
+want to generate your documentation.
+
+Here are some recommended steps to get started with Sphinx:
+
+#. Create a lightweight virtual environment for building the documentation. This can save a lot of time when building and publishing documentation remotely, as we'll show with `ReadTheDocs <https://readthedocs.org/>`__.
+
+    .. code:: bash
+        
+        # create new environment, press enter to accept
+        conda create -n docs_env python=3.9
+
+        # activate environment
+        conda activate docs_env
+
+        # install requirements stored in `docs` 
+        # (may differ from our file depending on your needs)
+        (docs_env) cd docs
+        (docs_env) pip install -r requirements.txt
+
+#. Inside your virtual environment, run ``sphinx-quickstart`` to creates a lot of the boilerplate configurations. This will guide you through a set of questions, such as your project details. We recommend creating separate ``source`` and ``build`` directories.
+#. Build the documentation, e.g. with ``make html``.
+#. Open ``docs/build/html/index.html`` in a browser to see your initial documentation!
+
+Editing your documentation
+--------------------------
+
+The ``index.rst`` file will serve as the "homepage" for your documentation (built into ``index.html``).
+Typically, people have the same content as their README. Before you copy-and-paste
+the contents (!), you can directly insert the contents with the following line.
+
+.. code:: rst
+
+    .. include:: ../../README.rst
+
+.. note::
+
+    `reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__
+    is the default plaintext markup language used by Sphinx. At this point, you may be thinking:
+    *"But my README is a Markdown file (.md)..."*. While there are `tools <https://www.sphinx-doc.org/en/master/usage/markdown.html>`__
+    to make Sphinx compatible with Markdown, I think you will save yourself more headaches to simply
+    switch to reStructuredText. There are also `online tools <https://cloudconvert.com/md-to-rst>`__
+    to help you with that.
+
+
+Adding new pages to your documentation amount to:
+
+#. Creating new RST files.
+#. Including them in your ``index.rst`` file.
+#. Rebuilding the documentation, e.g. with ``make html``.
+
+You may also need to edit the ``conf.py`` file to use different features.
+Check out our `index.rst <https://raw.githubusercontent.com/ebezzam/python-dev-tips/feat/docs/docs/source/index.rst>`__
+and `conf.py <https://github.com/ebezzam/python-dev-tips/blob/feat/docs/docs/source/conf.py>`__
+files for example configurations.
+
+
+You can do a clean build of your documentation with the following commands:
+
+.. code:: bash
+
+    make clean
+    make html
+
+
+Pro-tips
+--------
+
+* Changing to the ReadTheDocs theme inside `conf.py <https://github.com/ebezzam/python-dev-tips/blob/ec6b15c6718b96e2c1a00496d2cf7005755d006c/docs/source/conf.py#L75>`__.
+* `Intersphinx <https://docs.readthedocs.io/en/stable/guides/intersphinx.html>`__ for linking to other documentations.
+  In the ``conf.py`` file: `add <https://github.com/ebezzam/python-dev-tips/blob/ec6b15c6718b96e2c1a00496d2cf7005755d006c/docs/source/conf.py#L43>`__
+  the Sphinx extension, and `link <https://github.com/ebezzam/python-dev-tips/blob/ec6b15c6718b96e2c1a00496d2cf7005755d006c/docs/source/conf.py#L54>`__
+  to the other documentation. Inside your documentation you can link to the other library, e.g.
+  for data types:
+
+  .. code:: Python
+
+    ...
+
+    """
+    Parameters
+    ----------
+    filter : :py:class:`~numpy.ndarray`
+    """
+
+    ...
+
+  which renders as in :func:`pydevtips.fftconvolve.RFFTConvolve.__init__` 
+  with a clickable link to NumPy's documentation.
+* `Mock modules <https://github.com/ebezzam/python-dev-tips/blob/ec6b15c6718b96e2c1a00496d2cf7005755d006c/docs/source/conf.py#L24>`__ to keep your documentation virtual environment light.
+* `Add the path <https://github.com/ebezzam/python-dev-tips/blob/feat/docs/docs/source/conf.py#L22>`__ 
+  to your package, so that it doesn't have to be installed (again keeping your documentation environment light!).
+* `Automate year <https://github.com/ebezzam/python-dev-tips/blob/ec6b15c6718b96e2c1a00496d2cf7005755d006c/docs/source/conf.py#L32>`__.
+
+
+Publishing
+----------
+
+With a set of HTML files, there are many ways to publish your documentation online.
+We present one approach through `ReadTheDocs <https://readthedocs.org/>`__ (RTD), which is
+free and very popular among Python developers. Another popular free options is through
+`GitHub Pages <https://pages.github.com/>`__. I prefer RTD to not have the GitHub username or
+organization in the documentation URL.
+
+To publish on RTD:
+
+#. Make an account: https://readthedocs.org/accounts/signup/
+#. Import a project from the `dashboard <https://readthedocs.org/dashboard/>`__. There are two ways to do this: (1) linking your GitHub account and selecting one of your **public** repositories, or (2) importing the project manually. When linking to GitHub, the documentation is re-built whenever there are changes to the selected branch.
+
+You can (optionally) define a `.readthedocs.yaml <>`__ 
+file to ensure a build environment as close as possible to your local machine.

docs/source/fftconvolve.rst

@@ -1,5 +1,5 @@
-FFT Convolve
-============
+Class example
+=============
 
 .. GENERATE DOCUMENTATION FOR ALL CLASSES
 .. .. automodule:: pydevtips.fftconvolve
@@ -8,7 +8,7 @@ FFT Convolve
 ..     :special-members: __init__, __call__
 
 
-.. GENERATE ONE AT A TIME WITH CUSTOM TEXT
+.. GENERATE INDIVIDUALLY WITH CUSTOM TEXT
 
 There are two classes in this module for performing convolution in the frequency domain with a fixed filter.
 

docs/source/index.rst

@@ -13,10 +13,15 @@
 Contents
 --------
 
+.. toctree::
+
+   documentation
+
 .. toctree::
    :caption: Code
 
    fftconvolve
+   utils
 
 
 Indices and tables

docs/source/utils.rst

@@ -0,0 +1,10 @@
+Function example
+================
+
+.. GENERATE DOCUMENTATION FOR ALL FUNCTIONS
+.. .. automodule:: pydevtips.utils
+
+
+.. GENERATE INDIVIDUALLY
+.. autofunction:: pydevtips.utils.add
+

pydevtips/fftconvolve.py

@@ -50,7 +50,7 @@ class RFFTConvolve(FFTConvolveBase):
     """Real FFT convolve."""
 
     def __init__(self, filter, length) -> None:
-        r"""
+        """
         Create convolver that uses a real-valued filter.
 
         Parameters
@@ -66,11 +66,11 @@ def __init__(self, filter, length) -> None:
         super(RFFTConvolve, self).__init__(filter, length)
 
     def _compute_filter_frequency_response(self):
-        r"""Compute the filter frequency response."""
+        """Compute the filter frequency response."""
         return np.fft.rfft(self.filter, n=self.pad_length)
 
     def __call__(self, signal) -> np.ndarray:
-        r"""
+        """
         Apply the real-valued filter to the signal, in the frequency domain.
 
         Parameters

pydevtips/utils.py

@@ -0,0 +1,25 @@
+"""
+Utility functions.
+"""
+
+
+def add(a, b):
+    """
+    Add two integers.
+
+    Parameters
+    ----------
+    a : int
+        First integer.
+    b : int
+        Second integer.
+
+    Returns
+    -------
+    result : int
+        Sum of inputs.
+
+    """
+    assert isinstance(a, int)
+    assert isinstance(b, int)
+    return a + b