├── .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 | [](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 |
--------------------------------------------------------------------------------