Merge pull request #1 from readthedocs-examples/bootstrap

Bootstrap basic example contents for 1.0

README.md

@@ -1,2 +1,72 @@
-# example-mkdocs-basic
-A basic MkDocs project for Read the Docs
+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).
+
+📚 [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.
+
+⚙️ [.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`.
+
+⚙️ [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.
+
+📍 [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/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/).
+
+💡 [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.
+
+💡 [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`.
+
+🔢 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/).
+
+📜 [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).
+
+⁉️ 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).
+
+
+Example Project usage
+---------------------
+
+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!).
+
+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 (MkDocs etc.)
+pip install -r docs/requirements.txt
+
+# Run the mkdocs development server
+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 copying this code in order to get started with your documentation, you need to:
+
+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
+----------------------
+
+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/api.md

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

docs/index.md

@@ -1,17 +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
+
+    This project is under active development.
 
-    mkdocs.yml    # The configuration file.
-    docs/
-        index.md  # The documentation homepage.
-        ...       # Other markdown pages, images and other files.

docs/requirements.in

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

docs/requirements.txt

@@ -1 +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
+    # 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']
+```

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,16 @@
-site_name: My Docs
+site_name: Basic MkDocs Example Project
+theme:
+  name: readthedocs
+  highlightjs: true
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        # See: https://mkdocstrings.github.io/python/usage/
+        python:
+          options:
+            docstring_style: sphinx
+markdown_extensions:
+  - markdown_include.include:
+      base_path: .
+  - admonition

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