From 510aac9bd1202d2a58f6edb18939e5d0f7351e5f Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 6 Jul 2022 15:35:20 +0200 Subject: [PATCH 1/8] Raw pandoc conversion of README.rst from Sphinx example project --- README.md | 126 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 124 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index ae31640..4201819 100644 --- a/README.md +++ b/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. From a31ebe5a807b09a60ea48978350e8961b0f37f45 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 6 Jul 2022 15:35:36 +0200 Subject: [PATCH 2/8] Use readthedocs theme --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index c97182f..c68ea1d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1 +1,2 @@ site_name: My Docs +theme: readthedocs From 018d2e96386e4998b00f8ee67cd4db661f0baa7d Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 6 Jul 2022 16:16:58 +0200 Subject: [PATCH 3/8] WIP: Now upgraded with some auto-generated API documentation --- README.md | 16 ++++----- README.rst | 83 +++++++++++++++++++++++++++++++++++++++++++ docs/index.md | 4 +++ docs/requirements.in | 2 ++ docs/requirements.txt | 1 + lumache.py | 34 ++++++++++++++++++ mkdocs.yml | 3 ++ pyproject.toml | 8 +++++ 8 files changed, 143 insertions(+), 8 deletions(-) create mode 100644 README.rst create mode 100644 docs/requirements.in create mode 100644 lumache.py create mode 100644 pyproject.toml diff --git a/README.md b/README.md index 4201819..2ffa4cf 100644 --- a/README.md +++ b/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). diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..d405f28 --- /dev/null +++ b/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 `__. + +📚 `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 `_ + Read the Docs Build configuration is stored in ``.readthedocs.yaml``. +📍 `docs/requirements.txt `_ and `docs/requirements.in `_ + Python dependencies are `pinned `_ (uses `pip-tools `_). +💡 `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 `_ + Sphinx can automatically extract API documentation directly from Python modules, using for instance the ``:autofunction:`` directive. +💡 `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 `__. +📜 `README.rst `_ + Contents of this ``README.rst`` are visible on Github and included on `the documentation index page `_ (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 `_. + + +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 `_: + +.. 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 `_. + +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 `_. + + +Read the Docs tutorial +---------------------- + +To get started with Read the Docs, you may also refer to the `Read the Docs tutorial `__. +It provides a full walk-through of building an example project similar to the one in this repository. diff --git a/docs/index.md b/docs/index.md index 000ea34..2e7ed1e 100644 --- a/docs/index.md +++ b/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 diff --git a/docs/requirements.in b/docs/requirements.in new file mode 100644 index 0000000..e91d069 --- /dev/null +++ b/docs/requirements.in @@ -0,0 +1,2 @@ +mkdocs +mkdocstrings[python] diff --git a/docs/requirements.txt b/docs/requirements.txt index 9f37075..ef92fbb 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1 +1,2 @@ mkdocs==1.3.0 +mkdocstrings==0.19.0[python] diff --git a/lumache.py b/lumache.py new file mode 100644 index 0000000..49f0c0e --- /dev/null +++ b/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"] diff --git a/mkdocs.yml b/mkdocs.yml index c68ea1d..bfd0ac5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,2 +1,5 @@ site_name: My Docs theme: readthedocs +plugins: + - search + - mkdocstrings diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..14a2dda --- /dev/null +++ b/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"] From f74b76ecda4e66259312c162b97570adbedf602d Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Fri, 8 Jul 2022 16:37:11 +0200 Subject: [PATCH 4/8] Upgrading MkDocs example project to be almost 1:1 with Sphinx example --- README.md | 114 +++++++++++++++--------------------------- docs/api.md | 3 ++ docs/index.md | 24 ++++----- docs/requirements.in | 1 + docs/requirements.txt | 66 +++++++++++++++++++++++- docs/usage.md | 34 +++++++++++++ mkdocs.yml | 17 +++++-- test.md | 26 ++++++++++ 8 files changed, 192 insertions(+), 93 deletions(-) create mode 100644 docs/api.md create mode 100644 docs/usage.md create mode 100644 test.md diff --git a/README.md b/README.md index 2ffa4cf..e8c29fe 100644 --- a/README.md +++ b/README.md @@ -1,100 +1,66 @@ -Example: Basic Sphinx project for Read the Docs +Example: Basic MkDocs 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) +[![Documentation Status](https://readthedocs.org/projects/example-mkdocs-basic/badge/?version=latest)](https://example-mkdocs-basic.readthedocs.io/en/latest/?badge=latest) -This example shows the an integration of a basic Sphinx project with +This example shows the an integration of a basic MkDocs 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/) +📚 [docs/](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/docs/)
+A basic MkDocs project lives in `docs/`, it was generated using +MkDocs defaults. All the `*.md` make up sections in the +documentation. - 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-mkdocs-basic/blob/main/.readthedocs.yaml)
+Read the Docs Build configuration is stored in `.readthedocs.yaml`. -⚙️ [.readthedocs.yaml](https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/.readthedocs.yaml) +⚙️ [mkdocs.yml](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/mkdocs.yaml)
+A basic [MkDocs configuration](https://www.mkdocs.org/user-guide/configuration/) is stored here, including a few extensions for MkDocs and Markdown. Add your own configurations here, such as extensions and themes. Remember that many extensions and themes require additional Python packages to be installed. - Read the Docs Build configuration is stored in `.readthedocs.yaml`. +📍 [docs/requirements.txt](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/docs/requirements.txt) and [docs/requirements.in](https://github.com/readthedocs-examples/example-mkdocs-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/)) here. Make sure to add your Python dependencies to `requirements.txt` or if you choose [pip-tools](https://pip-tools.readthedocs.io/en/latest/), edit `docs/requirements.in` and remember to run to run `pip-compile docs/requirements.in`. -📍 [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) +💡 [docs/api.md](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/docs/api.md)
+We add our example Python module `lumache` in order to auto-generate an API reference. To do this, we use the `:::` syntax, you can read more in the [mkdocstrings documentation](https://mkdocstrings.github.io/). - 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/usage.md](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/docs/usage.md)
+We also include some direct links to a function from the API reference, as well as embedding documentation for the example function `lumache.get_random_recipe`. This functionality is also from the [mkdocstrings](https://mkdocstrings.github.io/python/) extension. -💡 [docs/api.rst](https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/docs/api.rst) +💡 [lumache.py](https://github.com/readthedocs-examples/example-mkdocs-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. We use the [Sphinx convention](https://pythonhosted.org/an_example_pypi_project/sphinx.html#function-definitions) for docstrings, however you are free to edit `mkdocs.yml` to change this option to `google` or `numpy`. -: By adding our example Python module `lumache` in the - reStructuredText directive `:autosummary:`, Sphinx will - automatically scan this module and generate API docs. +🔢 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-mkdocs-basic.readthedocs.io](https://example-mkdocs-basic.readthedocs.io/en/latest/). -💡 [docs/usage.rst](https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/docs/usage.rst) +📜 [README.rst](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/README.rst)
+Contents of this `README.md` are visible on Github and included on +[the documentation index +page](https://example-mkdocs-basic.readthedocs.io/en/latest/) +(Don\'t Repeat Yourself). - Sphinx can automatically extract API documentation directly from - Python modules, using for instance the `:autofunction:` directive. +⁉️ 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-mkdocs-basic/issues). -💡 [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. +Example Project usage +--------------------- -🔢 Git tags versioning +This project has a standard MkDocs layout which is built by Read the Docs almost the same way that you would build it locally (on your own laptop!). - 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/). +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): -📜 [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.) +```console +# Install required Python dependencies (MkDocs 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 +# Run the mkdocs development server +mkdocs serve ``` Using the example in your own project @@ -108,7 +74,7 @@ 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 +- Customize all `docs/*.md` files and copy in `mkdocs.yaml` - Add your own Python project, replacing the `pyproject.toml` configuration and `lumache.py` module. - Rebuild the documenation locally to see that it works. diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..24b0824 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,3 @@ +# API Reference + +::: lumache diff --git a/docs/index.md b/docs/index.md index 2e7ed1e..d489af8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,21 +1,15 @@ -# Welcome to MkDocs +{!README.md!} -For full documentation visit [mkdocs.org](https://www.mkdocs.org). +# Welcome to Lumache's documentation! -## Commands +**Lumache** (/lu\'make/) is a Python library for cooks and food lovers +that creates recipes mixing random ingredients. It pulls data from the +[Open Food Facts database](https://world.openfoodfacts.org/) and offers +a *simple* and *intuitive* API. -* `mkdocs new [dir-name]` - Create a new project. -* `mkdocs serve` - Start the live-reloading docs server. -* `mkdocs build` - Build the documentation site. -* `mkdocs -h` - Print help message and exit. +Check out the [usage](usage) section for further information, including how to [install](usage#installation) the project. -## Project layout +!!! note - mkdocs.yml # The configuration file. - docs/ - index.md # The documentation homepage. - ... # Other markdown pages, images and other files. + This project is under active development. -# Reference - -::: lumache diff --git a/docs/requirements.in b/docs/requirements.in index e91d069..bec300c 100644 --- a/docs/requirements.in +++ b/docs/requirements.in @@ -1,2 +1,3 @@ mkdocs mkdocstrings[python] +markdown-include diff --git a/docs/requirements.txt b/docs/requirements.txt index ef92fbb..f6cb652 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,66 @@ +# +# This file is autogenerated by pip-compile with python 3.10 +# To update, run: +# +# pip-compile docs/requirements.in +# +click==8.1.3 + # via mkdocs +ghp-import==2.1.0 + # via mkdocs +griffe==0.22.0 + # via mkdocstrings-python +importlib-metadata==4.12.0 + # via mkdocs +jinja2==3.1.2 + # via + # mkdocs + # mkdocstrings +markdown==3.3.7 + # via + # markdown-include + # mkdocs + # mkdocs-autorefs + # mkdocstrings + # pymdown-extensions +markdown-include==0.6.0 + # via -r docs/requirements.in +markupsafe==2.1.1 + # via + # jinja2 + # mkdocstrings +mergedeep==1.3.4 + # via mkdocs mkdocs==1.3.0 -mkdocstrings==0.19.0[python] + # via + # -r docs/requirements.in + # mkdocs-autorefs + # mkdocstrings +mkdocs-autorefs==0.4.1 + # via mkdocstrings +mkdocstrings[python]==0.19.0 + # via + # -r docs/requirements.in + # mkdocstrings-python +mkdocstrings-python==0.7.1 + # via mkdocstrings +packaging==21.3 + # via mkdocs +pymdown-extensions==9.5 + # via mkdocstrings +pyparsing==3.0.9 + # via packaging +python-dateutil==2.8.2 + # via ghp-import +pyyaml==6.0 + # via + # mkdocs + # pyyaml-env-tag +pyyaml-env-tag==0.1 + # via mkdocs +six==1.16.0 + # via python-dateutil +watchdog==2.1.9 + # via mkdocs +zipp==3.8.0 + # via importlib-metadata diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..efd1a2a --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,34 @@ +Usage +===== + +Installation +------------ + +To use Lumache, first install it using pip: + +```console +(.venv) $ pip install lumache +``` + +Creating recipes +---------------- + +To retrieve a list of random ingredients, you can use the +`lumache.get_random_ingredients()` function: + +::: lumache.get_random_ingredients + options: + show_root_heading: true + +
+ +The `kind` parameter should be either `"meat"`, `"fish"`, or `"veggies"`. +Otherwise, [`get_random_ingredients`][lumache.get_random_ingredients] will raise an exception [`lumache.InvalidKindError`](/api#lumache.InvalidKindError). + +For example: + +```python +>>> import lumache +>>> lumache.get_random_ingredients() +['shells', 'gorgonzola', 'parsley'] +``` diff --git a/mkdocs.yml b/mkdocs.yml index bfd0ac5..2a5a12e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,16 @@ -site_name: My Docs -theme: readthedocs +site_name: Basic MkDocs Example Project +theme: + name: readthedocs + highlightjs: true plugins: - search - - mkdocstrings + - mkdocstrings: + handlers: + # See: https://mkdocstrings.github.io/python/usage/ + python: + options: + docstring_style: sphinx +markdown_extensions: + - markdown_include.include: + base_path: . + - admonition diff --git a/test.md b/test.md new file mode 100644 index 0000000..dc258c4 --- /dev/null +++ b/test.md @@ -0,0 +1,26 @@ +Welcome to Lumache\'s documentation! +==================================== + +**Lumache** (/lu\'make/) is a Python library for cooks and food lovers +that creates recipes mixing random ingredients. It pulls data from the +[Open Food Facts database](https://world.openfoodfacts.org/) and offers +a *simple* and *intuitive* API. + +Check out the `usage`{.interpreted-text role="doc"} section for further +information, including how to `installation`{.interpreted-text +role="ref"} the project. + +::: {.note} +::: {.title} +Note +::: + +This project is under active development. +::: + +Contents +-------- + +::: {.toctree} +Home \ usage api +::: From 8e6bd6aa1817ddeaeb63a71a68f41503d2edd173 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Fri, 8 Jul 2022 16:45:30 +0200 Subject: [PATCH 5/8] Remove auto-generated line-wraps, we can add semantic wraps later --- README.md | 36 +++++++++--------------------------- 1 file changed, 9 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index e8c29fe..bcd50a4 100644 --- a/README.md +++ b/README.md @@ -3,16 +3,10 @@ Example: Basic MkDocs project for Read the Docs [![Documentation Status](https://readthedocs.org/projects/example-mkdocs-basic/badge/?version=latest)](https://example-mkdocs-basic.readthedocs.io/en/latest/?badge=latest) -This example shows the an integration of a basic MkDocs 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). +This example shows the an integration of a basic MkDocs 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-mkdocs-basic/blob/main/docs/)
-A basic MkDocs project lives in `docs/`, it was generated using -MkDocs defaults. All the `*.md` make up sections in the -documentation. +A basic MkDocs project lives in `docs/`, it was generated using MkDocs defaults. All the `*.md` make up sections in the documentation. ⚙️ [.readthedocs.yaml](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/.readthedocs.yaml)
Read the Docs Build configuration is stored in `.readthedocs.yaml`. @@ -21,9 +15,7 @@ Read the Docs Build configuration is stored in `.readthedocs.yaml`. A basic [MkDocs configuration](https://www.mkdocs.org/user-guide/configuration/) is stored here, including a few extensions for MkDocs and Markdown. Add your own configurations here, such as extensions and themes. Remember that many extensions and themes require additional Python packages to be installed. 📍 [docs/requirements.txt](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/docs/requirements.txt) and [docs/requirements.in](https://github.com/readthedocs-examples/example-mkdocs-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/)) here. Make sure to add your Python dependencies to `requirements.txt` or if you choose [pip-tools](https://pip-tools.readthedocs.io/en/latest/), edit `docs/requirements.in` and remember to run to run `pip-compile 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/)) here. Make sure to add your Python dependencies to `requirements.txt` or if you choose [pip-tools](https://pip-tools.readthedocs.io/en/latest/), edit `docs/requirements.in` and remember to run to run `pip-compile docs/requirements.in`. 💡 [docs/api.md](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/docs/api.md)
We add our example Python module `lumache` in order to auto-generate an API reference. To do this, we use the `:::` syntax, you can read more in the [mkdocstrings documentation](https://mkdocstrings.github.io/). @@ -39,10 +31,7 @@ We use a basic versioning mechanism by adding a git tag for every release of the [example-mkdocs-basic.readthedocs.io](https://example-mkdocs-basic.readthedocs.io/en/latest/). 📜 [README.rst](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/README.rst)
-Contents of this `README.md` are visible on Github and included on -[the documentation index -page](https://example-mkdocs-basic.readthedocs.io/en/latest/) -(Don\'t Repeat Yourself). +Contents of this `README.md` are visible on Github and included on [the documentation index page](https://example-mkdocs-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-mkdocs-basic/issues). @@ -66,25 +55,18 @@ mkdocs serve 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 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: +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/*.md` files and copy in `mkdocs.yaml` -- Add your own Python project, replacing the `pyproject.toml` - configuration and `lumache.py` module. +- 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). +- 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. +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. From c1776334db01140e0f484100705da8232e050d67 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Fri, 8 Jul 2022 16:46:19 +0200 Subject: [PATCH 6/8] Remove README.rst artifact from pandoc import --- README.rst | 83 ------------------------------------------------------ 1 file changed, 83 deletions(-) delete mode 100644 README.rst diff --git a/README.rst b/README.rst deleted file mode 100644 index d405f28..0000000 --- a/README.rst +++ /dev/null @@ -1,83 +0,0 @@ -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 `__. - -📚 `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 `_ - Read the Docs Build configuration is stored in ``.readthedocs.yaml``. -📍 `docs/requirements.txt `_ and `docs/requirements.in `_ - Python dependencies are `pinned `_ (uses `pip-tools `_). -💡 `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 `_ - Sphinx can automatically extract API documentation directly from Python modules, using for instance the ``:autofunction:`` directive. -💡 `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 `__. -📜 `README.rst `_ - Contents of this ``README.rst`` are visible on Github and included on `the documentation index page `_ (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 `_. - - -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 `_: - -.. 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 `_. - -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 `_. - - -Read the Docs tutorial ----------------------- - -To get started with Read the Docs, you may also refer to the `Read the Docs tutorial `__. -It provides a full walk-through of building an example project similar to the one in this repository. From 20d00c77cc02b99529f5ff7f14c8683019c1a499 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Fri, 8 Jul 2022 16:53:24 +0200 Subject: [PATCH 7/8] Improve steps on how to use the example project --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index bcd50a4..7c00111 100644 --- a/README.md +++ b/README.md @@ -59,12 +59,12 @@ If you are new to Read the Docs, you may want to refer to the [Read the Docs Use 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/*.md` files and copy in `mkdocs.yaml` -- 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). +1. place your `docs/` folder alongside your Python project. If you are starting a new project, you can adapt the `pyproject.toml` example configuration. +1. use your existing project repository or create a new repository on Github, GitLab, Bitbucket or another host supported by Read the Docs. +1. copy in `mkdocs.yaml`, `.readthedocs.yml` and the `docs/` folder into your project. Customize all the files, replacing example contents. +1. Rebuild the documenation locally to see that it works. +1. *Finally*, 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 ---------------------- From a531e29e4d2a879a445a6eff9d56d284112c1cb5 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Fri, 8 Jul 2022 16:55:06 +0200 Subject: [PATCH 8/8] Remove WIP artifact --- test.md | 26 -------------------------- 1 file changed, 26 deletions(-) delete mode 100644 test.md diff --git a/test.md b/test.md deleted file mode 100644 index dc258c4..0000000 --- a/test.md +++ /dev/null @@ -1,26 +0,0 @@ -Welcome to Lumache\'s documentation! -==================================== - -**Lumache** (/lu\'make/) is a Python library for cooks and food lovers -that creates recipes mixing random ingredients. It pulls data from the -[Open Food Facts database](https://world.openfoodfacts.org/) and offers -a *simple* and *intuitive* API. - -Check out the `usage`{.interpreted-text role="doc"} section for further -information, including how to `installation`{.interpreted-text -role="ref"} the project. - -::: {.note} -::: {.title} -Note -::: - -This project is under active development. -::: - -Contents --------- - -::: {.toctree} -Home \ usage api -:::