docs using jupyter book

.gitignore

@@ -3,4 +3,7 @@ __pycache__/
 *.egg-info/
 .venv/
 dist/
-build
+build
+.docs_venv
+_build
+_archive

.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

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

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

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

docs/intro.md

@@ -0,0 +1,3 @@
+## Welcome to NIR docs
+
+Happy you're here. Content coming soon!

docs/requirements.txt

@@ -0,0 +1,7 @@
+jupyter-book
+matplotlib
+numpy
+sphinx-inline-tabs
+sphinx-examples
+sphinx-proof
+sphinx-hoverxref

docs/samplepage.md

@@ -0,0 +1 @@
+# hello

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