From 51ae02d3cd1d0d958ce8d1ef52a39323cbed3f99 Mon Sep 17 00:00:00 2001 From: Filippo Luca Ferretti <102977828+flferretti@users.noreply.github.com> Date: Wed, 4 Oct 2023 13:05:39 +0200 Subject: [PATCH] Add .readthedocs file and docs folder (#6) --- .readthedocs.yaml | 11 +++++++++++ docs/Makefile | 20 ++++++++++++++++++++ docs/make.bat | 35 +++++++++++++++++++++++++++++++++++ docs/requirements.txt | 2 ++ docs/source/api.rst | 7 +++++++ docs/source/conf.py | 35 +++++++++++++++++++++++++++++++++++ docs/source/index.rst | 22 ++++++++++++++++++++++ docs/source/usage.rst | 34 ++++++++++++++++++++++++++++++++++ 8 files changed, 166 insertions(+) create mode 100644 .readthedocs.yaml create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/requirements.txt create mode 100644 docs/source/api.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/usage.rst diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..a92dca4c2 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,11 @@ +version: "2" + +build: + os: "ubuntu-22.04" + tools: + python: "3.10" + +sphinx: + configuration: docs/source/conf.py + +formats: all \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..d0c3cbf10 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 000000000..6247f7e23 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 000000000..53fc1f32e --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +sphinx==7.1.2 +sphinx-rtd-theme==1.3.0rc1 diff --git a/docs/source/api.rst b/docs/source/api.rst new file mode 100644 index 000000000..ec94338a6 --- /dev/null +++ b/docs/source/api.rst @@ -0,0 +1,7 @@ +API +=== + +.. autosummary:: + :toctree: generated + + lumache diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 000000000..6e9e8c087 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,35 @@ +# Configuration file for the Sphinx documentation builder. + +# -- Project information + +project = 'Lumache' +copyright = '2021, Graziella' +author = 'Graziella' + +release = '0.1' +version = '0.1.0' + +# -- General configuration + +extensions = [ + 'sphinx.ext.duration', + 'sphinx.ext.doctest', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', +] + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3/', None), + 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), +} +intersphinx_disabled_domains = ['std'] + +templates_path = ['_templates'] + +# -- Options for HTML output + +html_theme = 'sphinx_rtd_theme' + +# -- Options for EPUB output +epub_show_urls = 'footnote' diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 000000000..03d09a55d --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,22 @@ +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 `_ +and offers a *simple* and *intuitive* API. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + +.. note:: + + This project is under active development. + +Contents +-------- + +.. toctree:: + + usage + api diff --git a/docs/source/usage.rst b/docs/source/usage.rst new file mode 100644 index 000000000..924afcf6c --- /dev/null +++ b/docs/source/usage.rst @@ -0,0 +1,34 @@ +Usage +===== + +.. _installation: + +Installation +------------ + +To use Lumache, first install it using pip: + +.. code-block:: console + + (.venv) $ pip install lumache + +Creating recipes +---------------- + +To retrieve a list of random ingredients, +you can use the ``lumache.get_random_ingredients()`` function: + +.. autofunction:: lumache.get_random_ingredients + +The ``kind`` parameter should be either ``"meat"``, ``"fish"``, +or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients` +will raise an exception. + +.. autoexception:: lumache.InvalidKindError + +For example: + +>>> import lumache +>>> lumache.get_random_ingredients() +['shells', 'gorgonzola', 'parsley'] +