From c2700fc911ffd19b5fac047a5de1aad0d4150827 Mon Sep 17 00:00:00 2001 From: guillemdb Date: Mon, 12 Sep 2022 20:10:22 +0200 Subject: [PATCH] Update docs command: Notebook theme and better notebook support Signed-off-by: guillemdb --- mloq.yaml | 1 + src/mloq/assets/docs/conf.txt | 29 ++++++++++++++++++---- src/mloq/assets/docs/makefile_docs.txt | 12 ++++++++- src/mloq/assets/docs/requirements-docs.txt | 13 ++++++---- src/mloq/commands/docs.py | 1 + tests/commands/test_docs.py | 4 ++- 6 files changed, 48 insertions(+), 12 deletions(-) diff --git a/mloq.yaml b/mloq.yaml index 2fa44552..8e889564 100644 --- a/mloq.yaml +++ b/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: diff --git a/src/mloq/assets/docs/conf.txt b/src/mloq/assets/docs/conf.txt index ad6f6d54..3039c19e 100644 --- a/src/mloq/assets/docs/conf.txt +++ b/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, diff --git a/src/mloq/assets/docs/makefile_docs.txt b/src/mloq/assets/docs/makefile_docs.txt index 45dba3a0..a159fb71 100644 --- a/src/mloq/assets/docs/makefile_docs.txt +++ b/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 \ No newline at end of file diff --git a/src/mloq/assets/docs/requirements-docs.txt b/src/mloq/assets/docs/requirements-docs.txt index f4d7d870..73d60cca 100644 --- a/src/mloq/assets/docs/requirements-docs.txt +++ b/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 \ No newline at end of file +sphinx-autoapi==1.9.0 +sphinxcontrib-mermaid==0.7.1 +sphinx_book_theme==0.3.3 +jupyter-cache==0.5.0 \ No newline at end of file diff --git a/src/mloq/commands/docs.py b/src/mloq/commands/docs.py index 99ac23a4..23c6fde9 100644 --- a/src/mloq/commands/docs.py +++ b/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 diff --git a/tests/commands/test_docs.py b/tests/commands/test_docs.py index f6e5c6d9..ca60c4a8 100644 --- a/tests/commands/test_docs.py +++ b/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(