WIP: Now upgraded with some auto-generated API documentation

Author: benjaoming

README.md

@@ -11,17 +11,17 @@ Tutorial](https://docs.readthedocs.io/en/stable/tutorial/index.html).
 
 📚 [docs/](https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/docs/)
 
-:   A basic Sphinx project lives in `docs/`, it was generated using
+    A basic Sphinx project lives in `docs/`, it was generated using
     Sphinx defaults. All the `*.rst` make up sections in the
     documentation.
 
 ⚙️ [.readthedocs.yaml](https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/.readthedocs.yaml)
 
-:   Read the Docs Build configuration is stored in `.readthedocs.yaml`.
+   Read the Docs Build configuration is stored in `.readthedocs.yaml`.
 
 📍 [docs/requirements.txt](https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/docs/requirements.txt) and [docs/requirements.in](https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/docs/requirements.in)
 
-:   Python dependencies are
+    Python dependencies are
     [pinned](https://docs.readthedocs.io/en/latest/guides/reproducible-builds.html)
     (uses [pip-tools](https://pip-tools.readthedocs.io/en/latest/)).
 
@@ -33,32 +33,32 @@ Tutorial](https://docs.readthedocs.io/en/stable/tutorial/index.html).
 
 💡 [docs/usage.rst](https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/docs/usage.rst)
 
-:   Sphinx can automatically extract API documentation directly from
+    Sphinx can automatically extract API documentation directly from
     Python modules, using for instance the `:autofunction:` directive.
 
 💡 [lumache.py](https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/lumache.py)
 
-:   API docs are generated for this example Python module - they use
+    API docs are generated for this example Python module - they use
     *docstrings* directly in the documentation, notice how this shows up
     in the rendered documentation.
 
 🔢 Git tags versioning
 
-:   We use a basic versioning mechanism by adding a git tag for every
+    We use a basic versioning mechanism by adding a git tag for every
     release of the example project. All releases and their version
     numbers are visible on
     [example-sphinx-basic.readthedocs.io](https://example-sphinx-basic.readthedocs.io/en/latest/).
 
 📜 [README.rst](https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/README.rst)
 
-:   Contents of this `README.rst` are visible on Github and included on
+    Contents of this `README.rst` are visible on Github and included on
     [the documentation index
     page](https://example-sphinx-basic.readthedocs.io/en/latest/)
     (Don\'t Repeat Yourself).
 
 ⁉️ Questions / comments
 
-:   If you have questions related to this example, feel free to can ask
+    If you have questions related to this example, feel free to can ask
     them as a Github issue
     [here](https://github.com/readthedocs-examples/example-sphinx-basic/issues).
 

README.rst

@@ -0,0 +1,83 @@
+Example: Basic Sphinx project for Read the Docs
+===============================================
+
+.. image:: https://readthedocs.org/projects/example-sphinx-basic/badge/?version=latest
+    :target: https://example-sphinx-basic.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation Status
+
+.. This README.rst should work on Github and is also included in the Sphinx documentation project in docs/ - therefore, README.rst uses absolute links for most things so it renders properly on GitHub
+
+This example shows the an integration of a basic Sphinx project with Read the Docs. You're encouraged to view it to get inspiration and copy & paste from the files in the source code. If you are using Read the Docs for the first time, have a look at the official `Read the Docs Tutorial <https://docs.readthedocs.io/en/stable/tutorial/index.html>`__.
+
+📚 `docs/ <https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/docs/>`_
+    A basic Sphinx project lives in ``docs/``, it was generated using Sphinx defaults. All the ``*.rst`` make up sections in the documentation.
+⚙️ `.readthedocs.yaml <https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/.readthedocs.yaml>`_
+    Read the Docs Build configuration is stored in ``.readthedocs.yaml``.
+📍 `docs/requirements.txt <https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/docs/requirements.txt>`_ and `docs/requirements.in <https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/docs/requirements.in>`_
+    Python dependencies are `pinned <https://docs.readthedocs.io/en/latest/guides/reproducible-builds.html>`_ (uses `pip-tools <https://pip-tools.readthedocs.io/en/latest/>`_).
+💡 `docs/api.rst <https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/docs/api.rst>`_
+    By adding our example Python module ``lumache`` in the reStructuredText directive ``:autosummary:``, Sphinx will automatically scan this module and generate API docs.
+💡 `docs/usage.rst <https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/docs/usage.rst>`_
+    Sphinx can automatically extract API documentation directly from Python modules, using for instance the ``:autofunction:`` directive.
+💡 `lumache.py <https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/lumache.py>`_
+    API docs are generated for this example Python module - they use *docstrings* directly in the documentation, notice how this shows up in the rendered documentation.
+🔢 Git tags versioning
+    We use a basic versioning mechanism by adding a git tag for every release of the example project. All releases and their version numbers are visible on `example-sphinx-basic.readthedocs.io <https://example-sphinx-basic.readthedocs.io/en/latest/>`__.
+📜 `README.rst <https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/README.rst>`_
+    Contents of this ``README.rst`` are visible on Github and included on `the documentation index page <https://example-sphinx-basic.readthedocs.io/en/latest/>`_ (Don't Repeat Yourself).
+⁉️ Questions / comments
+    If you have questions related to this example, feel free to can ask them as a Github issue `here <https://github.com/readthedocs-examples/example-sphinx-basic/issues>`_.
+
+
+Sphinx Example Project usage
+----------------------------
+
+This project has a standard Sphinx layout which is built by Read the Docs almost the same way that you would build it locally (on your own laptop!).
+
+You can build and view this documentation project locally - we recommend that you activate `a local Python virtual environment first <https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment>`_:
+
+.. code-block:: console
+
+    # Install required Python dependencies (Sphinx etc.)
+    pip install -r docs/requirements.txt
+
+    # Enter the Sphinx project
+    cd docs/
+    
+    # Run the raw sphinx-build command
+    sphinx-build -M html . _build/
+
+
+You can also build the documentation locally with ``make``:
+
+.. code-block:: console
+
+    # Enter the Sphinx project
+    cd docs/
+    
+    # Build with make
+    make html
+    
+    # Open with your preferred browser, pointing it to the documentation index page
+    firefox _build/html/index.html
+
+
+Using the example in your own project
+-------------------------------------
+
+If you are new to Read the Docs, you may want to refer to the `Read the Docs User documentation <https://docs.readthedocs.io/>`_.
+
+If you are copying this code in order to get started with your documentation, you need to:
+
+* Create a new repository on Github, GitLab, Bitbucket or another host supported by Read the Docs
+* Customize all ``docs/*.rst`` files
+* Add your own Python project, replacing the ``pyproject.toml`` configuration and ``lumache.py`` module.
+* Rebuild the documenation locally to see that it works.
+* Register your project on Read the Docs, see `Importing Your Documentation <https://docs.readthedocs.io/en/stable/intro/import-guide.html>`_.
+
+
+Read the Docs tutorial
+----------------------
+
+To get started with Read the Docs, you may also refer to the `Read the Docs tutorial <https://docs.readthedocs.io/en/stable/tutorial/>`__.
+It provides a full walk-through of building an example project similar to the one in this repository.

docs/index.md

@@ -15,3 +15,7 @@ For full documentation visit [mkdocs.org](https://www.mkdocs.org).
     docs/
         index.md  # The documentation homepage.
         ...       # Other markdown pages, images and other files.
+
+# Reference
+
+::: lumache

docs/requirements.in

@@ -0,0 +1,2 @@
+mkdocs
+mkdocstrings[python]

docs/requirements.txt

@@ -1 +1,2 @@
 mkdocs==1.3.0
+mkdocstrings==0.19.0[python]

lumache.py

@@ -0,0 +1,34 @@
+"""
+Lumache - Python library for cooks and food lovers.
+
+This is a Python docstring, we can use Markdown syntax here because
+our API documentation library understands it (mkdocstrings).
+
+    # Import lumache
+    import lumache
+
+    # Call its only function
+    get_random_ingredients(kind=["cheeses"])
+
+"""
+
+__version__ = "0.1.0"
+
+
+class InvalidKindError(Exception):
+    """Raised if the kind is invalid."""
+
+    pass
+
+
+def get_random_ingredients(kind=None):
+    """
+    Return a list of random ingredients as strings.
+
+    :param kind: Optional "kind" of ingredients.
+    :type kind: list[str] or None
+    :raise lumache.InvalidKindError: If the kind is invalid.
+    :return: The ingredients list.
+    :rtype: list[str]
+    """
+    return ["shells", "gorgonzola", "parsley"]

mkdocs.yml

@@ -1,2 +1,5 @@
 site_name: My Docs
 theme: readthedocs
+plugins:
+  - search
+  - mkdocstrings

pyproject.toml

@@ -0,0 +1,8 @@
+[build-system]
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "lumache"
+authors = [{name = "Graziella", email = "graziella@lumache"}]
+dynamic = ["version", "description"]