diff --git a/.gitignore b/.gitignore index 8f2d938..de2e932 100644 --- a/.gitignore +++ b/.gitignore @@ -3,4 +3,7 @@ __pycache__/ *.egg-info/ .venv/ dist/ -build \ No newline at end of file +build +.docs_venv +_build +_archive diff --git a/.readthedocs.yaml b/.readthedocs.yaml index aa209bb..dc5644e 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -14,19 +14,23 @@ build: # nodejs: "19" # rust: "1.64" # golang: "1.19" + jobs: + pre_build: + # Generate on-the-fly Sphinx configuration from Jupyter Book's _config.yml + - "jupyter-book config sphinx docs/" -# Build documentation in the "docs/" directory with Sphinx -sphinx: - configuration: docs/conf.py +# # Build documentation in the "docs/" directory with Sphinx +# sphinx: +# configuration: docs/conf.py # Optionally build your docs in additional formats such as PDF and ePub -# formats: -# - pdf +formats: + - pdf # - epub # Optional but recommended, declare the Python requirements required # to build your documentation # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html -# python: -# install: -# - requirements: docs/requirements.txt +python: + install: + - requirements: docs/requirements.txt diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d0c3cbf..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# 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/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..93ef7fa --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,74 @@ +# Book settings +# Learn more at https://jupyterbook.org/customize/config.html +# Comprehensive example: https://github.com/executablebooks/jupyter-book/blob/master/docs/_config.yml + +title: NIR Docs +author: Steven Abreu, Felix Bauer, Jason Eshraghian, Matthias Jobst, Gregor Lenz, Jens Egholm Pedersen, Sadique Sheik +logo: logo.png + +# Force re-execution of notebooks on each build. +# See https://jupyterbook.org/content/execute.html +execute: + execute_notebooks: force + +# Define the name of the latex output file for PDF builds +latex: + latex_documents: + targetname: book.tex + +# Add a bibtex file so that we can create citations +bibtex_bibfiles: + - references.bib + +# Information about where the book exists on the web +repository: + url: https://github.com/neuromorphs/nir # Online location of your book + path_to_book: docs # Optional path to your book, relative to the repository root + branch: docs # Which branch of the repository should be used when creating links (optional)# TODO + +# Add GitHub buttons to your book +# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository +html: + use_issues_button: true + use_repository_button: true + +sphinx: + config: + intersphinx_mapping: + ebp: + - "https://executablebooks.org/en/latest/" + - null + myst-parser: + - "https://myst-parser.readthedocs.io/en/latest/" + - null + myst-nb: + - "https://myst-nb.readthedocs.io/en/latest/" + - null + sphinx: + - "https://www.sphinx-doc.org/en/master" + - null + nbformat: + - "https://nbformat.readthedocs.io/en/latest" + - null + sd: + - "https://sphinx-design.readthedocs.io/en/latest" + - null + sphinxproof: + - "https://sphinx-proof.readthedocs.io/en/latest/" + - null + hoverxref_intersphinx: + - "sphinxproof" + mathjax3_config: + tex: + macros: + "N": "\\mathbb{N}" + "floor": ["\\lfloor#1\\rfloor", 1] + "bmat": ["\\left[\\begin{array}"] + "emat": ["\\end{array}\\right]"] + + extra_extensions: + - sphinx.ext.intersphinx + - sphinx_inline_tabs + - sphinx_proof + - sphinx_examples + - hoverxref.extension diff --git a/docs/_toc.yml b/docs/_toc.yml new file mode 100644 index 0000000..96472f7 --- /dev/null +++ b/docs/_toc.yml @@ -0,0 +1,9 @@ +# Table of contents +# Learn more at https://jupyterbook.org/customize/toc.html + +format: jb-book +root: intro +parts: +- caption: Basic examples 🪄 + chapters: + - file: samplepage diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..9d4dff9 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,38 @@ +############################################################################### +# Auto-generated by `jupyter-book config` +# If you wish to continue using _config.yml, make edits to that file and +# re-generate this one. +############################################################################### +author = 'Steven Abreu, Felix Bauer, Jason Eshraghian, Matthias Jobst, Gregor Lenz, Jens Egholm Pedersen, Sadique Sheik' +bibtex_bibfiles = ['references.bib'] +comments_config = {'hypothesis': False, 'utterances': False} +copyright = '2022' +exclude_patterns = ['**.ipynb_checkpoints', '.DS_Store', 'Thumbs.db', '_build'] +extensions = ['sphinx_togglebutton', 'sphinx_copybutton', 'myst_nb', 'jupyter_book', 'sphinx_thebe', 'sphinx_comments', 'sphinx_external_toc', 'sphinx.ext.intersphinx', 'sphinx_design', 'sphinx_book_theme', 'sphinx_inline_tabs', 'sphinx_proof', 'sphinx_examples', 'hoverxref.extension', 'sphinxcontrib.bibtex', 'sphinx_jupyterbook_latex'] +external_toc_exclude_missing = False +external_toc_path = '_toc.yml' +hoverxref_intersphinx = ['sphinxproof'] +html_baseurl = '' +html_favicon = '' +html_logo = 'logo.png' +html_sourcelink_suffix = '' +html_theme = 'sphinx_book_theme' +html_theme_options = {'search_bar_text': 'Search this book...', 'launch_buttons': {'notebook_interface': 'classic', 'binderhub_url': '', 'jupyterhub_url': '', 'thebe': False, 'colab_url': ''}, 'path_to_docs': 'docs', 'repository_url': 'https://github.com/neuromorphs/nir', 'repository_branch': 'docs', 'extra_footer': '', 'home_page_in_toc': True, 'announcement': '', 'analytics': {'google_analytics_id': ''}, 'use_repository_button': True, 'use_edit_page_button': False, 'use_issues_button': True} +html_title = 'NIR Docs' +intersphinx_mapping = {'ebp': ['https://executablebooks.org/en/latest/', None], 'myst-parser': ['https://myst-parser.readthedocs.io/en/latest/', None], 'myst-nb': ['https://myst-nb.readthedocs.io/en/latest/', None], 'sphinx': ['https://www.sphinx-doc.org/en/master', None], 'nbformat': ['https://nbformat.readthedocs.io/en/latest', None], 'sd': ['https://sphinx-design.readthedocs.io/en/latest', None], 'sphinxproof': ['https://sphinx-proof.readthedocs.io/en/latest/', None]} +latex_engine = 'pdflatex' +mathjax3_config = {'tex': {'macros': {'N': '\\mathbb{N}', 'floor': ['\\lfloor#1\\rfloor', 1], 'bmat': ['\\left[\\begin{array}'], 'emat': ['\\end{array}\\right]']}}} +myst_enable_extensions = ['colon_fence', 'dollarmath', 'linkify', 'substitution', 'tasklist'] +myst_url_schemes = ['mailto', 'http', 'https'] +nb_execution_allow_errors = False +nb_execution_cache_path = '' +nb_execution_excludepatterns = [] +nb_execution_in_temp = False +nb_execution_mode = 'force' +nb_execution_timeout = 30 +nb_output_stderr = 'show' +numfig = True +pygments_style = 'sphinx' +suppress_warnings = ['myst.domains'] +use_jupyterbook_latex = True +use_multitoc_numbering = True diff --git a/docs/intro.md b/docs/intro.md new file mode 100644 index 0000000..a15042d --- /dev/null +++ b/docs/intro.md @@ -0,0 +1,3 @@ +## Welcome to NIR docs + +Happy you're here. Content coming soon! diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 6247f7e..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@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 0000000..95ddb8d --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,7 @@ +jupyter-book +matplotlib +numpy +sphinx-inline-tabs +sphinx-examples +sphinx-proof +sphinx-hoverxref diff --git a/docs/samplepage.md b/docs/samplepage.md new file mode 100644 index 0000000..8954bb9 --- /dev/null +++ b/docs/samplepage.md @@ -0,0 +1 @@ +# hello diff --git a/docs/source/api.rst b/docs/source/api.rst deleted file mode 100644 index ec94338..0000000 --- a/docs/source/api.rst +++ /dev/null @@ -1,7 +0,0 @@ -API -=== - -.. autosummary:: - :toctree: generated - - lumache diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index f857b03..0000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,35 +0,0 @@ -# Configuration file for the Sphinx documentation builder. - -# -- Project information - -project = 'NIR' -copyright = '2023, NIR' -author = 'Steven Abreu, Felix Bauer, Jason Eshraghian, Matthias Jobst, Gregor Lenz, Jens Egholm Pedersen, Sadique Sheik' - -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 deleted file mode 100644 index 03d09a5..0000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,22 +0,0 @@ -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 deleted file mode 100644 index 924afcf..0000000 --- a/docs/source/usage.rst +++ /dev/null @@ -1,34 +0,0 @@ -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'] - diff --git a/postBuild b/postBuild new file mode 100644 index 0000000..cb6f5fd --- /dev/null +++ b/postBuild @@ -0,0 +1,6 @@ +#!/bin/bash +# This script is invoked by the mybinder.org service which can detect, +# display and execute any .ipynb Jupyter Notebook in the repository. +set -e +# We reuse the requirements from the documentation project +pip install -r docs/requirements.txt