Documentation update

.github/workflows/publish-docs.yml

@@ -40,8 +40,8 @@ jobs:
     - name: Build documentation
       run: |
         cd docs
-        poetry run bash autogen_docs.sh
-        poetry run make html
+        poetry run sphinx-apidoc --force --implicit-namespaces --module-first -o reference ../src/pydna
+        poetry run sphinx-build -n -W --keep-going -b html ./ ./_build/
 
     - name: Deploy to GitHub pages 🚀
       # Deploy only when master changes

docs/README.md

@@ -93,3 +93,18 @@ For further customization, you can edit the `custom.css` file.
 ## Misc
 
 Other changes, such as changing the favicon, the css etc., can be made in the `conf.py` file. See the [sphinx docs](https://www.sphinx-doc.org/en/master/usage/configuration.html) and the [sphinx-rtd-theme](https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html) docs for more information.
+
+## Build docs using Sphinx command line tools
+
+Command to be run from `path/to/docs`, i.e. from within the `docs` package folder: 
+
+Options:
+  - `--separate` to build separate pages for each (sub-)module
+
+```bash	
+# pwd: docs
+# apidoc
+sphinx-apidoc --force --implicit-namespaces --module-first -o reference ../src/pydna
+# build docs
+sphinx-build -n -W --keep-going -b html ./ ./_build/
+```

docs/conf.py

@@ -27,31 +27,65 @@
 
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autodoc.typehints",  # Automatically document type hints in function signatures
     "sphinx.ext.coverage",
     "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",  # Include links to the source code in the documentation
     "sphinx.ext.doctest",
-    "myst_parser",  # Allows to use markdown files instead of rst
     "sphinx.ext.viewcode",
     "sphinx.ext.autosummary",
     "numpydoc",
     "sphinx.ext.intersphinx",
-    "sphinx_rtd_theme",
+    # "sphinx_book_theme",
+    # new:
+    # "sphinx_new_tab_link",  # each link opens in a new tab
+    "myst_nb",  # Markdown and Jupyter Notebook support
+    # "sphinx_copybutton",  # add copy button to code blocks
 ]
 
+
+#  https://myst-nb.readthedocs.io/en/latest/computation/execute.html
+nb_execution_mode = "auto"
+
+myst_enable_extensions = ["dollarmath", "amsmath"]
+
+# Plotly support through require javascript library
+# https://myst-nb.readthedocs.io/en/latest/render/interactive.html#plotly
+html_js_files = [
+    "https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"
+]
+
+# https://myst-nb.readthedocs.io/en/latest/configuration.html
+# Execution
+nb_execution_raise_on_error = True
+# Rendering
+nb_merge_streams = True
+
+
 # Add mappings https://kev.inburke.com/kevin/sphinx-interlinks
 intersphinx_mapping = {
-    "biopython": ("https://biopython.org/docs/latest/api/", None),
+    "biopython": ("https://biopython.org/docs/latest", None),
     "python": ("http://docs.python.org/3.8", None),
 }
 
 # Settings to support markdown files
 source_suffix = {
     ".rst": "restructuredtext",
-    ".md": "markdown",
 }
 
 templates_path = ["_templates"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store",
+                    "future_release_names.md",
+                    "cookbook", # remove once cookbook works
+                    "jupyter_execute", # local build folder for notebooks (dev)
+                    "pydna_cheat_sheet",
+                    "pydna_session",
+                    "Makefile",
+                    "make",
+                    "autogen_docs",
+                    "README.md",
+                    "example_gallery.md",
+                    ]
 
 autodoc_member_order = "bysource"
 autodoc_preserve_defaults = True
@@ -61,7 +95,31 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = "sphinx_rtd_theme"
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+# See:
+# https://github.com/executablebooks/MyST-NB/blob/master/docs/conf.py
+# html_title = ""
+html_theme = "sphinx_book_theme"
+# html_logo = "_static/logo-wide.svg"
+# html_favicon = "_static/logo-square.svg"
+html_theme_options = {
+    "github_url": "https://github.com/pydna-group/pydna",
+    "repository_url": "https://github.com/pydna-group/pydna",
+    "repository_branch": "main",
+    "home_page_in_toc": True,
+    "path_to_docs": "docs",
+    "show_navbar_depth": 1,
+    "use_edit_page_button": True,
+    "use_repository_button": True,
+    "use_download_button": True,
+    "launch_buttons": {
+        "colab_url": "https://colab.research.google.com"
+        #     "binderhub_url": "https://mybinder.org",
+        #     "notebook_interface": "jupyterlab",
+    },
+    "navigation_with_keys": False,
+}
 html_static_path = ["_static"]
 
 texinfo_documents = [