From 79d08cfb49e62e045ccc91510d22af187b3356ec Mon Sep 17 00:00:00 2001 From: Badr-MOUFAD Date: Wed, 8 Nov 2023 15:23:48 +0100 Subject: [PATCH 01/20] setup``conf.py`` --- doc/conf.py | 32 ++++++++++++++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 58bf930e0..510742c9d 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -66,6 +66,9 @@ # custom ext, see ./sphinxext/gh_substitutions.py ] +# TODO comment this variable +is_stable_doc = False + myst_enable_extensions = [ "dollarmath", "amsmath" @@ -76,6 +79,8 @@ # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] +html_css_files = ["style.css"] + # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # source_suffix = ['.rst', '.md'] @@ -208,7 +213,7 @@ # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -#html_title = None +html_title = f"skglm {version} documentation" # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None @@ -241,7 +246,30 @@ #html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +html_sidebars = { + "**": [ + "sidebar/brand.html", + "sidebar/search.html", + "sidebar/navigation.html", + "sidebar/version.html", + ] +} + +# TODO write a comment +html_context = { + "is_stable_doc": is_stable_doc +} + +# TODO write a comment +if not is_stable_doc: + html_theme_options = { + "announcement": ( + "You are viewing the documentation of the dev version of " + "skglm which contains WIP features. " + "View stable version." + ) + } + # Additional templates that should be rendered to pages, maps page names to # template names. From 244f19cb742cb0ff1d455e61bd3ab16f521993ad Mon Sep 17 00:00:00 2001 From: Badr-MOUFAD Date: Wed, 8 Nov 2023 16:38:25 +0100 Subject: [PATCH 02/20] add version toggler --- doc/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index 510742c9d..acb5eb6d9 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -251,7 +251,7 @@ "sidebar/brand.html", "sidebar/search.html", "sidebar/navigation.html", - "sidebar/version.html", + "sidebar/version_toggler.html", ] } From 17f2856c8fbc193c52d8b0a488a19c8820aa8d8c Mon Sep 17 00:00:00 2001 From: Badr-MOUFAD Date: Wed, 8 Nov 2023 16:38:48 +0100 Subject: [PATCH 03/20] version toggler: template and style --- doc/_static/style.css | 25 +++++++++++++++++++++ doc/_templates/sidebar/version_toggler.html | 16 +++++++++++++ 2 files changed, 41 insertions(+) create mode 100644 doc/_static/style.css create mode 100644 doc/_templates/sidebar/version_toggler.html diff --git a/doc/_static/style.css b/doc/_static/style.css new file mode 100644 index 000000000..70fd2a4cd --- /dev/null +++ b/doc/_static/style.css @@ -0,0 +1,25 @@ +.announcement { + background-color: #1f77b4; +} + +.sidebar-version { + display: flex; + flex-direction: row; + align-items: center; + justify-content: space-between; + + border-bottom: 1px solid var(--color-sidebar-search-border); + border-top: 1px solid var(--color-sidebar-search-border); + + padding-top: var(--sidebar-search-input-spacing-vertical); + padding-bottom: var(--sidebar-search-input-spacing-vertical); + padding-left: var(--sidebar-item-spacing-horizontal); + padding-right: var(--sidebar-item-spacing-horizontal); +} + +.sidebar-version-selected { + border-radius: 0.25rem; + background-color: #ff7f0e; + color: white; + pointer-events: none; +} diff --git a/doc/_templates/sidebar/version_toggler.html b/doc/_templates/sidebar/version_toggler.html new file mode 100644 index 000000000..cea067f28 --- /dev/null +++ b/doc/_templates/sidebar/version_toggler.html @@ -0,0 +1,16 @@ +
+
Version
+ + +
From f9ebe62e2f67b81a08c94c7396ebb67605040529 Mon Sep 17 00:00:00 2001 From: Badr-MOUFAD Date: Wed, 8 Nov 2023 17:54:49 +0100 Subject: [PATCH 04/20] is_stable_version ---> is_stable_doc & fix doc path --- doc/_templates/sidebar/version_toggler.html | 4 ++-- doc/conf.py | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/_templates/sidebar/version_toggler.html b/doc/_templates/sidebar/version_toggler.html index cea067f28..48eb74b18 100644 --- a/doc/_templates/sidebar/version_toggler.html +++ b/doc/_templates/sidebar/version_toggler.html @@ -4,12 +4,12 @@ diff --git a/doc/conf.py b/doc/conf.py index acb5eb6d9..8c522043c 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -266,7 +266,7 @@ "announcement": ( "You are viewing the documentation of the dev version of " "skglm which contains WIP features. " - "View stable version." + "View stable version." ) } From da81ec08123897b9a84927ebff99eb9cb9aaa87e Mon Sep 17 00:00:00 2001 From: Badr-MOUFAD Date: Wed, 8 Nov 2023 19:26:13 +0100 Subject: [PATCH 05/20] add comments --- doc/conf.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 8c522043c..aba3c7d75 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -66,7 +66,7 @@ # custom ext, see ./sphinxext/gh_substitutions.py ] -# TODO comment this variable +# set it to True to build a stable version of the documentation is_stable_doc = False myst_enable_extensions = [ @@ -251,16 +251,18 @@ "sidebar/brand.html", "sidebar/search.html", "sidebar/navigation.html", - "sidebar/version_toggler.html", + "sidebar/version_toggler.html", # version toggler template ] } -# TODO write a comment +# these variables will be available in the sphinx templates html_context = { "is_stable_doc": is_stable_doc } -# TODO write a comment + +# when it's the dev version of the documentation, put a banner to warn the user +# and a link to switch to the dev version of doc if not is_stable_doc: html_theme_options = { "announcement": ( From c94def159eb22ca8fb6c6c6a45214b4b23a89efb Mon Sep 17 00:00:00 2001 From: Badr-MOUFAD Date: Thu, 9 Nov 2023 11:19:41 +0100 Subject: [PATCH 06/20] update makefile to persist stable doc --- doc/Makefile | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/doc/Makefile b/doc/Makefile index c592b30a2..b939d5920 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -9,6 +9,8 @@ BUILDDIR = _build GITHUB_PAGES_BRANCH = gh-pages OUTPUTDIR = _build/html +DOC_DIR = doc +STABLE_DOC_DIR = stable # User-friendly check for sphinx-build ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) @@ -136,5 +138,18 @@ coverage: install: touch $(OUTPUTDIR)/.nojekyll + + cd .. +# switch to GITHUB_PAGES_BRANCH where stable build is located + git fetch origin $(GITHUB_PAGES_BRANCH) + git checkout $(GITHUB_PAGES_BRANCH) +# move the content of the stable build to the output dir + if [ -d "$(STABLE_DOC_DIR)" ]; then \ + mv $(STABLE_DOC_DIR)/ $(DOC_DIR)/$(OUTPUTDIR); \ + fi +# switch back to main and get to doc directory + git checkout main + cd $(DOC_DIR) + ghp-import -m "Generate Pelican site [ci skip]" -b $(GITHUB_PAGES_BRANCH) $(OUTPUTDIR) git push origin $(GITHUB_PAGES_BRANCH) From 784cd511681ef91d2af108f498a34c9ef85fcbb7 Mon Sep 17 00:00:00 2001 From: Badr-MOUFAD Date: Thu, 9 Nov 2023 14:07:43 +0100 Subject: [PATCH 07/20] isolate instructions to add stable doc --- doc/Makefile | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index b939d5920..3a627bcf6 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -138,7 +138,11 @@ coverage: install: touch $(OUTPUTDIR)/.nojekyll + ghp-import -m "Generate Pelican site [ci skip]" -b $(GITHUB_PAGES_BRANCH) $(OUTPUTDIR) + git push origin $(GITHUB_PAGES_BRANCH) +.PHONY: add-stable-doc +add-stable-doc: cd .. # switch to GITHUB_PAGES_BRANCH where stable build is located git fetch origin $(GITHUB_PAGES_BRANCH) @@ -150,6 +154,3 @@ install: # switch back to main and get to doc directory git checkout main cd $(DOC_DIR) - - ghp-import -m "Generate Pelican site [ci skip]" -b $(GITHUB_PAGES_BRANCH) $(OUTPUTDIR) - git push origin $(GITHUB_PAGES_BRANCH) From 4f4859daa255a40023758cbbdc6dd4a2c3b1f124 Mon Sep 17 00:00:00 2001 From: Badr-MOUFAD Date: Thu, 9 Nov 2023 14:08:10 +0100 Subject: [PATCH 08/20] stable in artifact --- .circleci/config.yml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/.circleci/config.yml b/.circleci/config.yml index bcef5d4d6..880a586b7 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -78,9 +78,21 @@ jobs: chmod og= ~/.ssh/config cd doc; pip install ghp-import; + make add-stable-doc make install fi + # Add stable documentation + - run: + name: stable_doc + command: | + set -e + mkdir -p ~/.ssh + echo -e "Host *\nStrictHostKeyChecking no" > ~/.ssh/config + chmod og= ~/.ssh/config + cd doc; + make add-stable-doc + # Save the outputs - store_artifacts: path: doc/_build/html/ From bdd35961ca04ddd3154f9f0de0a52c5e0d3f8c54 Mon Sep 17 00:00:00 2001 From: Badr-MOUFAD Date: Thu, 9 Nov 2023 14:10:12 +0100 Subject: [PATCH 09/20] fix indentation --- .circleci/config.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 880a586b7..c18cd28e7 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -84,8 +84,8 @@ jobs: # Add stable documentation - run: - name: stable_doc - command: | + name: stable_doc + command: | set -e mkdir -p ~/.ssh echo -e "Host *\nStrictHostKeyChecking no" > ~/.ssh/config From adff9e9a8ec6657ed3a497092d2d7079d865ad40 Mon Sep 17 00:00:00 2001 From: Badr-MOUFAD Date: Thu, 9 Nov 2023 14:21:20 +0100 Subject: [PATCH 10/20] debug cd to doc after checkout dir --- doc/Makefile | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/Makefile b/doc/Makefile index 3a627bcf6..41d33d877 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -153,4 +153,5 @@ add-stable-doc: fi # switch back to main and get to doc directory git checkout main + ls cd $(DOC_DIR) From 971e1ce11873912c19a239acc433ead8e064ecf5 Mon Sep 17 00:00:00 2001 From: Badr-MOUFAD Date: Thu, 9 Nov 2023 14:34:46 +0100 Subject: [PATCH 11/20] more on debugging --- .circleci/config.yml | 2 +- doc/Makefile | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index c18cd28e7..f9d64e588 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -63,7 +63,7 @@ jobs: command: | cd doc; make clean; - make SPHINXOPTS=-v html; + make SPHINXOPTS=-v html-noplot; cd ..; diff --git a/doc/Makefile b/doc/Makefile index 41d33d877..4e0622ae5 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -143,15 +143,19 @@ install: .PHONY: add-stable-doc add-stable-doc: + pwd + ls cd .. # switch to GITHUB_PAGES_BRANCH where stable build is located git fetch origin $(GITHUB_PAGES_BRANCH) git checkout $(GITHUB_PAGES_BRANCH) # move the content of the stable build to the output dir if [ -d "$(STABLE_DOC_DIR)" ]; then \ + echo "stable copied"; \ mv $(STABLE_DOC_DIR)/ $(DOC_DIR)/$(OUTPUTDIR); \ fi # switch back to main and get to doc directory git checkout main + pwd ls cd $(DOC_DIR) From ad38244b1d7107ca6259691ad6cd034290841edd Mon Sep 17 00:00:00 2001 From: Badr-MOUFAD Date: Thu, 9 Nov 2023 14:38:21 +0100 Subject: [PATCH 12/20] more debugging --- doc/Makefile | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index 4e0622ae5..a757ae133 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -143,19 +143,17 @@ install: .PHONY: add-stable-doc add-stable-doc: - pwd - ls cd .. # switch to GITHUB_PAGES_BRANCH where stable build is located git fetch origin $(GITHUB_PAGES_BRANCH) git checkout $(GITHUB_PAGES_BRANCH) # move the content of the stable build to the output dir + pwd + ls if [ -d "$(STABLE_DOC_DIR)" ]; then \ echo "stable copied"; \ mv $(STABLE_DOC_DIR)/ $(DOC_DIR)/$(OUTPUTDIR); \ fi # switch back to main and get to doc directory git checkout main - pwd - ls cd $(DOC_DIR) From 7588045c48df020e9449d84424c0baa0e130009f Mon Sep 17 00:00:00 2001 From: Badr-MOUFAD Date: Thu, 9 Nov 2023 14:45:33 +0100 Subject: [PATCH 13/20] pull changes from gh-pages --- doc/Makefile | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doc/Makefile b/doc/Makefile index a757ae133..eb1891769 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -143,10 +143,17 @@ install: .PHONY: add-stable-doc add-stable-doc: + pwd + ls + cd .. + + pwd + ls # switch to GITHUB_PAGES_BRANCH where stable build is located git fetch origin $(GITHUB_PAGES_BRANCH) git checkout $(GITHUB_PAGES_BRANCH) + git pull origin $(GITHUB_PAGES_BRANCH) # move the content of the stable build to the output dir pwd ls @@ -156,4 +163,6 @@ add-stable-doc: fi # switch back to main and get to doc directory git checkout main + pwd + ls cd $(DOC_DIR) From a74cb744ecc541bd8a34e80a1a596f01b01325f0 Mon Sep 17 00:00:00 2001 From: Badr-MOUFAD Date: Thu, 9 Nov 2023 14:51:19 +0100 Subject: [PATCH 14/20] missing semicolon in makefile --- doc/Makefile | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index eb1891769..e710e0310 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -146,14 +146,14 @@ add-stable-doc: pwd ls - cd .. + cd ..; pwd ls # switch to GITHUB_PAGES_BRANCH where stable build is located - git fetch origin $(GITHUB_PAGES_BRANCH) - git checkout $(GITHUB_PAGES_BRANCH) - git pull origin $(GITHUB_PAGES_BRANCH) + git fetch origin $(GITHUB_PAGES_BRANCH); + git checkout $(GITHUB_PAGES_BRANCH); + git pull origin $(GITHUB_PAGES_BRANCH); # move the content of the stable build to the output dir pwd ls @@ -162,7 +162,7 @@ add-stable-doc: mv $(STABLE_DOC_DIR)/ $(DOC_DIR)/$(OUTPUTDIR); \ fi # switch back to main and get to doc directory - git checkout main + git checkout main; pwd ls - cd $(DOC_DIR) + cd $(DOC_DIR); From 4629a5135a485d5c2f4f8d62c2d3ac42591c53bc Mon Sep 17 00:00:00 2001 From: Badr-MOUFAD Date: Thu, 9 Nov 2023 14:56:56 +0100 Subject: [PATCH 15/20] workaround without ``cd ..`` --- doc/Makefile | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index e710e0310..930eb1a00 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -9,7 +9,6 @@ BUILDDIR = _build GITHUB_PAGES_BRANCH = gh-pages OUTPUTDIR = _build/html -DOC_DIR = doc STABLE_DOC_DIR = stable # User-friendly check for sphinx-build @@ -145,11 +144,6 @@ install: add-stable-doc: pwd ls - - cd ..; - - pwd - ls # switch to GITHUB_PAGES_BRANCH where stable build is located git fetch origin $(GITHUB_PAGES_BRANCH); git checkout $(GITHUB_PAGES_BRANCH); @@ -157,12 +151,8 @@ add-stable-doc: # move the content of the stable build to the output dir pwd ls - if [ -d "$(STABLE_DOC_DIR)" ]; then \ - echo "stable copied"; \ - mv $(STABLE_DOC_DIR)/ $(DOC_DIR)/$(OUTPUTDIR); \ - fi + mv ../$(STABLE_DOC_DIR)/ $(OUTPUTDIR); # switch back to main and get to doc directory git checkout main; pwd ls - cd $(DOC_DIR); From 0d8dfe0d884a0bc6361d5ba8a90f1e331032fa4f Mon Sep 17 00:00:00 2001 From: Badr-MOUFAD Date: Thu, 9 Nov 2023 15:05:24 +0100 Subject: [PATCH 16/20] rm semicolons --- doc/Makefile | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index 930eb1a00..33eced71e 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -145,14 +145,14 @@ add-stable-doc: pwd ls # switch to GITHUB_PAGES_BRANCH where stable build is located - git fetch origin $(GITHUB_PAGES_BRANCH); - git checkout $(GITHUB_PAGES_BRANCH); - git pull origin $(GITHUB_PAGES_BRANCH); + git fetch origin $(GITHUB_PAGES_BRANCH) + git checkout $(GITHUB_PAGES_BRANCH) + git pull origin $(GITHUB_PAGES_BRANCH) # move the content of the stable build to the output dir pwd ls - mv ../$(STABLE_DOC_DIR)/ $(OUTPUTDIR); + mv ../$(STABLE_DOC_DIR) $(OUTPUTDIR) # switch back to main and get to doc directory - git checkout main; + git checkout main pwd ls From b97e4696219143b459125f72db8cc6cb89dbdafc Mon Sep 17 00:00:00 2001 From: Badr-MOUFAD Date: Thu, 9 Nov 2023 15:13:56 +0100 Subject: [PATCH 17/20] clean ups makefile --- .circleci/config.yml | 2 +- doc/Makefile | 6 ------ 2 files changed, 1 insertion(+), 7 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index f9d64e588..c18cd28e7 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -63,7 +63,7 @@ jobs: command: | cd doc; make clean; - make SPHINXOPTS=-v html-noplot; + make SPHINXOPTS=-v html; cd ..; diff --git a/doc/Makefile b/doc/Makefile index 33eced71e..e2d6c7c79 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -142,17 +142,11 @@ install: .PHONY: add-stable-doc add-stable-doc: - pwd - ls # switch to GITHUB_PAGES_BRANCH where stable build is located git fetch origin $(GITHUB_PAGES_BRANCH) git checkout $(GITHUB_PAGES_BRANCH) git pull origin $(GITHUB_PAGES_BRANCH) # move the content of the stable build to the output dir - pwd - ls mv ../$(STABLE_DOC_DIR) $(OUTPUTDIR) # switch back to main and get to doc directory git checkout main - pwd - ls From 76ae8bb5da570bc5bcd44fdea00f5a8ef9d215c1 Mon Sep 17 00:00:00 2001 From: Badr-MOUFAD Date: Thu, 9 Nov 2023 15:33:44 +0100 Subject: [PATCH 18/20] CI trigger From b99912bebabd0553b27aac55064a09ecd9b3abd2 Mon Sep 17 00:00:00 2001 From: Badr-MOUFAD Date: Tue, 14 Nov 2023 10:20:13 +0100 Subject: [PATCH 19/20] version toggler before search bar --- doc/_static/style.css | 11 +++++------ doc/_templates/sidebar/version_toggler.html | 15 ++++++++------- doc/conf.py | 2 +- 3 files changed, 14 insertions(+), 14 deletions(-) diff --git a/doc/_static/style.css b/doc/_static/style.css index 70fd2a4cd..3deebf01f 100644 --- a/doc/_static/style.css +++ b/doc/_static/style.css @@ -8,16 +8,15 @@ align-items: center; justify-content: space-between; - border-bottom: 1px solid var(--color-sidebar-search-border); - border-top: 1px solid var(--color-sidebar-search-border); - - padding-top: var(--sidebar-search-input-spacing-vertical); - padding-bottom: var(--sidebar-search-input-spacing-vertical); padding-left: var(--sidebar-item-spacing-horizontal); padding-right: var(--sidebar-item-spacing-horizontal); + margin-top: 0px; } -.sidebar-version-selected { +.sidebar-version-selected>* { + display: flex; + align-items: center; + padding: 0.25em; border-radius: 0.25rem; background-color: #ff7f0e; color: white; diff --git a/doc/_templates/sidebar/version_toggler.html b/doc/_templates/sidebar/version_toggler.html index 48eb74b18..afd2a3e1f 100644 --- a/doc/_templates/sidebar/version_toggler.html +++ b/doc/_templates/sidebar/version_toggler.html @@ -1,16 +1,17 @@
-
Version
+ Version - diff --git a/doc/conf.py b/doc/conf.py index aba3c7d75..afa64bdef 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -249,9 +249,9 @@ html_sidebars = { "**": [ "sidebar/brand.html", + "sidebar/version_toggler.html", # version toggler template "sidebar/search.html", "sidebar/navigation.html", - "sidebar/version_toggler.html", # version toggler template ] } From ee3be509162de9837b6d9c66c844fbc586ffd5da Mon Sep 17 00:00:00 2001 From: Badr-MOUFAD Date: Tue, 14 Nov 2023 10:28:44 +0100 Subject: [PATCH 20/20] CI trigger