├── .gitignore ├── .readthedocs.yaml ├── README.md ├── docs ├── api.md ├── index.md ├── requirements.in ├── requirements.txt └── usage.md ├── lumache.py ├── mkdocs.yml └── pyproject.toml /.gitignore: -------------------------------------------------------------------------------- 1 | # Byte-compiled / optimized / DLL files 2 | __pycache__/ 3 | *.py[cod] 4 | *$py.class 5 | 6 | # C extensions 7 | *.so 8 | 9 | # Distribution / packaging 10 | .Python 11 | build/ 12 | develop-eggs/ 13 | dist/ 14 | downloads/ 15 | eggs/ 16 | .eggs/ 17 | lib/ 18 | lib64/ 19 | parts/ 20 | sdist/ 21 | var/ 22 | wheels/ 23 | pip-wheel-metadata/ 24 | share/python-wheels/ 25 | *.egg-info/ 26 | .installed.cfg 27 | *.egg 28 | MANIFEST 29 | 30 | # PyInstaller 31 | # Usually these files are written by a python script from a template 32 | # before PyInstaller builds the exe, so as to inject date/other infos into it. 33 | *.manifest 34 | *.spec 35 | 36 | # Installer logs 37 | pip-log.txt 38 | pip-delete-this-directory.txt 39 | 40 | # Unit test / coverage reports 41 | htmlcov/ 42 | .tox/ 43 | .nox/ 44 | .coverage 45 | .coverage.* 46 | .cache 47 | nosetests.xml 48 | coverage.xml 49 | *.cover 50 | *.py,cover 51 | .hypothesis/ 52 | .pytest_cache/ 53 | 54 | # Translations 55 | *.mo 56 | *.pot 57 | 58 | # Django stuff: 59 | *.log 60 | local_settings.py 61 | db.sqlite3 62 | db.sqlite3-journal 63 | 64 | # Flask stuff: 65 | instance/ 66 | .webassets-cache 67 | 68 | # Scrapy stuff: 69 | .scrapy 70 | 71 | # Sphinx documentation 72 | docs/_build/ 73 | 74 | # PyBuilder 75 | target/ 76 | 77 | # Jupyter Notebook 78 | .ipynb_checkpoints 79 | 80 | # IPython 81 | profile_default/ 82 | ipython_config.py 83 | 84 | # pyenv 85 | .python-version 86 | 87 | # pipenv 88 | # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. 89 | # However, in case of collaboration, if having platform-specific dependencies or dependencies 90 | # having no cross-platform support, pipenv may install dependencies that don't work, or not 91 | # install all needed dependencies. 92 | #Pipfile.lock 93 | 94 | # PEP 582; used by e.g. github.com/David-OConnor/pyflow 95 | __pypackages__/ 96 | 97 | # Celery stuff 98 | celerybeat-schedule 99 | celerybeat.pid 100 | 101 | # SageMath parsed files 102 | *.sage.py 103 | 104 | # Environments 105 | .env 106 | .venv 107 | env/ 108 | venv/ 109 | ENV/ 110 | env.bak/ 111 | venv.bak/ 112 | 113 | # Spyder project settings 114 | .spyderproject 115 | .spyproject 116 | 117 | # Rope project settings 118 | .ropeproject 119 | 120 | # mkdocs documentation 121 | /site 122 | 123 | # mypy 124 | .mypy_cache/ 125 | .dmypy.json 126 | dmypy.json 127 | 128 | # Pyre type checker 129 | .pyre/ 130 | -------------------------------------------------------------------------------- /.readthedocs.yaml: -------------------------------------------------------------------------------- 1 | # .readthedocs.yaml 2 | # Read the Docs configuration file 3 | # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details 4 | 5 | # Required 6 | version: 2 7 | 8 | # Set the version of Python and other tools you might need 9 | build: 10 | os: ubuntu-24.04 11 | tools: 12 | python: "3.12" 13 | 14 | mkdocs: 15 | configuration: mkdocs.yml 16 | 17 | # Optionally declare the Python requirements required to build your docs 18 | python: 19 | install: 20 | - requirements: docs/requirements.txt 21 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | Example: Basic MkDocs project for Read the Docs 2 | =============================================== 3 | 4 | [![Documentation Status](https://readthedocs.org/projects/example-mkdocs-basic/badge/?version=latest)](https://example-mkdocs-basic.readthedocs.io/en/latest/?badge=latest) 5 | 6 | This example shows 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). 7 | 8 | 📚 [docs/](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/docs/)
9 | A basic MkDocs project lives in `docs/`, it was generated using MkDocs defaults. All the `*.md` make up sections in the documentation. 10 | 11 | ⚙️ [.readthedocs.yaml](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/.readthedocs.yaml)
12 | Read the Docs Build configuration is stored in `.readthedocs.yaml`. 13 | 14 | ⚙️ [mkdocs.yml](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/mkdocs.yml)
15 | 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. 16 | 17 | 📍 [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)
18 | 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`. 19 | 20 | 💡 [docs/api.md](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/docs/api.md)
21 | 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/). 22 | 23 | 💡 [docs/usage.md](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/docs/usage.md)
24 | 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. 25 | 26 | 💡 [lumache.py](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/lumache.py)
27 | 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`. 28 | 29 | 🔢 Git tags versioning
30 | 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 31 | [example-mkdocs-basic.readthedocs.io](https://example-mkdocs-basic.readthedocs.io/en/latest/). 32 | 33 | 📜 [README.md](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/README.md)
34 | 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). 35 | 36 | ⁉️ Questions / comments
37 | 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). 38 | 39 | 40 | Example Project usage 41 | --------------------- 42 | 43 | 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!). 44 | 45 | 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): 46 | 47 | ```console 48 | # Install required Python dependencies (MkDocs etc.) 49 | pip install -r docs/requirements.txt 50 | 51 | # Run the mkdocs development server 52 | mkdocs serve 53 | ``` 54 | 55 | Using the example in your own project 56 | ------------------------------------- 57 | 58 | If you are new to Read the Docs, you may want to refer to the [Read the Docs User documentation](https://docs.readthedocs.io/). 59 | 60 | If you are copying this code in order to get started with your documentation, you need to: 61 | 62 | 1. place your `docs/` folder alongside your Python project. If you are starting a new project, you can adapt the `pyproject.toml` example configuration. 63 | 1. use your existing project repository or create a new repository on Github, GitLab, Bitbucket or another host supported by Read the Docs. 64 | 1. copy `mkdocs.yml`, `.readthedocs.yaml` and the `docs/` folder into your project. 65 | 1. customize all the files, replacing example contents. 66 | 1. Rebuild the documenation locally to see that it works. 67 | 1. *Finally*, register your project on Read the Docs, see [Importing Your Documentation](https://docs.readthedocs.io/en/stable/intro/import-guide.html). 68 | 69 | 70 | Read the Docs tutorial 71 | ---------------------- 72 | 73 | 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. 74 | -------------------------------------------------------------------------------- /docs/api.md: -------------------------------------------------------------------------------- 1 | # API Reference 2 | 3 | ::: lumache 4 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | {!README.md!} 2 | 3 | # Welcome to Lumache's documentation! 4 | 5 | **Lumache** (/lu\'make/) is a Python library for cooks and food lovers 6 | that creates recipes mixing random ingredients. It pulls data from the 7 | [Open Food Facts database](https://world.openfoodfacts.org/) and offers 8 | a *simple* and *intuitive* API. 9 | 10 | Check out the [usage](usage) section for further information, including how to [install](usage#installation) the project. 11 | 12 | !!! note 13 | 14 | This project is under active development. 15 | 16 | -------------------------------------------------------------------------------- /docs/requirements.in: -------------------------------------------------------------------------------- 1 | mkdocs 2 | mkdocstrings[python] 3 | markdown-include 4 | -------------------------------------------------------------------------------- /docs/requirements.txt: -------------------------------------------------------------------------------- 1 | # 2 | # This file is autogenerated by pip-compile with python 3.10 3 | # To update, run: 4 | # 5 | # pip-compile docs/requirements.in 6 | # 7 | click==8.1.3 8 | # via mkdocs 9 | ghp-import==2.1.0 10 | # via mkdocs 11 | griffe==0.22.0 12 | # via mkdocstrings-python 13 | importlib-metadata==4.12.0 14 | # via mkdocs 15 | jinja2==3.1.2 16 | # via 17 | # mkdocs 18 | # mkdocstrings 19 | markdown==3.3.7 20 | # via 21 | # markdown-include 22 | # mkdocs 23 | # mkdocs-autorefs 24 | # mkdocstrings 25 | # pymdown-extensions 26 | markdown-include==0.6.0 27 | # via -r docs/requirements.in 28 | markupsafe==2.1.1 29 | # via 30 | # jinja2 31 | # mkdocstrings 32 | mergedeep==1.3.4 33 | # via mkdocs 34 | mkdocs==1.3.0 35 | # via 36 | # -r docs/requirements.in 37 | # mkdocs-autorefs 38 | # mkdocstrings 39 | mkdocs-autorefs==0.4.1 40 | # via mkdocstrings 41 | mkdocstrings[python]==0.19.0 42 | # via 43 | # -r docs/requirements.in 44 | # mkdocstrings-python 45 | mkdocstrings-python==0.7.1 46 | # via mkdocstrings 47 | packaging==21.3 48 | # via mkdocs 49 | pymdown-extensions==9.5 50 | # via mkdocstrings 51 | pyparsing==3.0.9 52 | # via packaging 53 | python-dateutil==2.8.2 54 | # via ghp-import 55 | pyyaml==6.0 56 | # via 57 | # mkdocs 58 | # pyyaml-env-tag 59 | pyyaml-env-tag==0.1 60 | # via mkdocs 61 | six==1.16.0 62 | # via python-dateutil 63 | watchdog==2.1.9 64 | # via mkdocs 65 | zipp==3.8.0 66 | # via importlib-metadata 67 | -------------------------------------------------------------------------------- /docs/usage.md: -------------------------------------------------------------------------------- 1 | Usage 2 | ===== 3 | 4 | Installation 5 | ------------ 6 | 7 | To use Lumache, first install it using pip: 8 | 9 | ```console 10 | (.venv) $ pip install lumache 11 | ``` 12 | 13 | Creating recipes 14 | ---------------- 15 | 16 | To retrieve a list of random ingredients, you can use the 17 | `lumache.get_random_ingredients()` function: 18 | 19 | ::: lumache.get_random_ingredients 20 | options: 21 | show_root_heading: true 22 | 23 |
24 | 25 | The `kind` parameter should be either `"meat"`, `"fish"`, or `"veggies"`. 26 | Otherwise, [`get_random_ingredients`][lumache.get_random_ingredients] will raise an exception [`lumache.InvalidKindError`](/api#lumache.InvalidKindError). 27 | 28 | For example: 29 | 30 | ```python 31 | >>> import lumache 32 | >>> lumache.get_random_ingredients() 33 | ['shells', 'gorgonzola', 'parsley'] 34 | ``` 35 | -------------------------------------------------------------------------------- /lumache.py: -------------------------------------------------------------------------------- 1 | """ 2 | Lumache - Python library for cooks and food lovers. 3 | 4 | This is a Python docstring, we can use Markdown syntax here because 5 | our API documentation library understands it (mkdocstrings). 6 | 7 | # Import lumache 8 | import lumache 9 | 10 | # Call its only function 11 | get_random_ingredients(kind=["cheeses"]) 12 | 13 | """ 14 | 15 | __version__ = "0.1.0" 16 | 17 | 18 | class InvalidKindError(Exception): 19 | """Raised if the kind is invalid.""" 20 | 21 | pass 22 | 23 | 24 | def get_random_ingredients(kind=None): 25 | """ 26 | Return a list of random ingredients as strings. 27 | 28 | :param kind: Optional "kind" of ingredients. 29 | :type kind: list[str] or None 30 | :raise lumache.InvalidKindError: If the kind is invalid. 31 | :return: The ingredients list. 32 | :rtype: list[str] 33 | """ 34 | return ["shells", "gorgonzola", "parsley"] 35 | -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: Basic MkDocs Example Project 2 | theme: 3 | name: readthedocs 4 | highlightjs: true 5 | plugins: 6 | - search 7 | - mkdocstrings: 8 | handlers: 9 | # See: https://mkdocstrings.github.io/python/usage/ 10 | python: 11 | options: 12 | docstring_style: sphinx 13 | markdown_extensions: 14 | - markdown_include.include: 15 | base_path: . 16 | - admonition 17 | -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [build-system] 2 | requires = ["flit_core >=3.2,<4"] 3 | build-backend = "flit_core.buildapi" 4 | 5 | [project] 6 | name = "lumache" 7 | authors = [{name = "Graziella", email = "graziella@lumache"}] 8 | dynamic = ["version", "description"] 9 | --------------------------------------------------------------------------------