Upgrading MkDocs example project to be almost 1:1 with Sphinx example

Author: benjaoming

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/)<br>
+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)<br>
+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)<br>
+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)<br>
+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)<br>
+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)<br>
+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)<br>
+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<br>
+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)<br>
+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<br>
+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.

docs/api.md

@@ -0,0 +1,3 @@
+# API Reference
+
+::: lumache

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

docs/requirements.in

@@ -1,2 +1,3 @@
 mkdocs
 mkdocstrings[python]
+markdown-include

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

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
+
+<br>
+
+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']
+```

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

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 \<self\> usage api
+:::