Bootstrap basic example contents for 1.0

README.md

@@ -1,2 +1,124 @@
-# example-mkdocs-basic
-A basic MkDocs project for Read the Docs
+Example: Basic Sphinx project for Read the Docs
+===============================================
+
+[![Documentation Status](https://readthedocs.org/projects/example-sphinx-basic/badge/?version=latest)](https://example-sphinx-basic.readthedocs.io/en/latest/?badge=latest)
+
+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):
+
+``` {.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`:
+
+``` {.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.

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 +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"]