Update docs command: Notebook theme and better notebook support

Signed-off-by: guillemdb <guillem@fragile.tech>

mloq.yaml

@@ -36,6 +36,7 @@ docs:
   copyright_holder: ${license.copyright_holder}
   copyright_year: ${license.copyright_year}
   default_branch: ${globals.default_branch}
+  project_url: ${globals.project_url}
   deploy_docs: true
 
 git:

src/mloq/assets/docs/conf.txt

@@ -39,7 +39,7 @@ master_doc = "index"
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "sphinx.ext.autodoc",
+    #"sphinx.ext.autodoc",
     "autoapi.extension",
     "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
@@ -50,9 +50,10 @@ extensions = [
     "sphinx.ext.napoleon",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.autodoc.typehints",
-    "myst_parser",
-    # "sphinx.ext.githubpages",
-    # "m2r",
+    "sphinx_book_theme",
+    "myst_nb",
+    "sphinxcontrib.mermaid",
+    "sphinx.ext.githubpages",
 ]
 suppress_warnings = ["image.nonlocal_uri"]
 autodoc_typehints = "description"
@@ -94,7 +95,25 @@ exclude_patterns = []
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
+html_title = ""
+html_theme = "sphinx_book_theme"
+# html_logo = "_static/logo-wide.svg"
+# html_favicon = "_static/logo-square.svg"
+html_theme_options = {
+    "github_url": "{{docs.project_url}}",
+    "repository_url": "{{docs.project_url}}",
+    "repository_branch": "gh-pages",
+    "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": {
+        "binderhub_url": "https://mybinder.org",
+        "notebook_interface": "classic",
+    },
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

src/mloq/assets/docs/makefile_docs.txt

@@ -7,7 +7,9 @@ SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = build
-NOTEBOOKS_DIR = .
+NOTEBOOKS_SRC_DIR  = ../notebooks
+NOTEBOOKS_BUILD_DIR  = ./source/notebooks
+
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -24,7 +26,15 @@ help:
 server:
 	python3 -m http.server --directory  build/html/
 
+#	rm -rf source/notebooks
+#	cp -r ../notebooks ./source/notebooks
+
 .PHONY: test
 test:
+	if [ -e "${NOTEBOOKS_SRC_DIR}" ] && [ -e "${NOTEBOOKS_BUILD_DIR}" ]; then \
+		echo "${NOTEBOOKS_BUILD_DIR} Updating notebook folder."; \
+		rm -rf "${NOTEBOOKS_BUILD_DIR}"; \
+		cp -r "${NOTEBOOKS_SRC_DIR}"  "${NOTEBOOKS_BUILD_DIR}"; \
+	fi
 	make html
 	make server

src/mloq/assets/docs/requirements-docs.txt

@@ -1,6 +1,9 @@
-sphinx==4.3.0
-linkify-it-py==1.0.2
-myst-parser==0.15.2
+sphinx==4.5.0
+linkify-it-py==2.0.0
+myst-parser==0.18.0
+myst-nb==0.16.0
 ruyaml==0.19.2
-sphinx-autoapi==1.8.4
-sphinx-rtd-theme==1.0.0
+sphinx-autoapi==1.9.0
+sphinxcontrib-mermaid==0.7.1
+sphinx_book_theme==0.3.3
+jupyter-cache==0.5.0

src/mloq/commands/docs.py

@@ -64,6 +64,7 @@ class DocsCMD(Command):
     copyright_holder = param.String("${docs.author}", doc="Copyright holder")
     deploy_docs = param.Boolean(True, doc="Deploy docs to GitHub Pages?")
     default_branch = param.String("${globals.default_branch}", doc="Branch used to build the docs")
+    project_url = param.String("${globals.project_url}", doc="GitHub project url")
     files = tuple(DOCS_FILES)
 
     @property

tests/commands/test_docs.py

@@ -15,6 +15,7 @@
 from mloq.writer import CMDRecord
 
 
+dummy_project_url = "https://test.com"
 docs_conf = {
     "docs": dict(
         disable=False,
@@ -25,6 +26,7 @@
         copyright_holder="test_copyright_holder",
         copyright_year="1990",
         default_branch="test_branch",
+        project_url=dummy_project_url,
     ),
 }
 
@@ -38,7 +40,7 @@
             "email": "test_email",
             "description": "test_description",
             "open_source": True,
-            "project_url": "???",
+            "project_url": dummy_project_url,
         },
         "license": {"copyright_holder": "test_holder", "copyright_year": 1990},
         "docs": dict(