From 95467981e8f877a2cd5d6b4ebfe3b72725de5a0a Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Sun, 6 Feb 2022 12:35:30 +0300 Subject: [PATCH 1/4] Try sphinx-book-theme@master --- .github/workflows/sphinx.yml | 2 +- docs/conf.py | 23 ++++++++++++----------- requirements-docs.txt | 11 ++++++++--- 3 files changed, 21 insertions(+), 15 deletions(-) diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml index 617bafe4..fea526b3 100644 --- a/.github/workflows/sphinx.yml +++ b/.github/workflows/sphinx.yml @@ -34,7 +34,7 @@ jobs: - name: Set Up Python uses: actions/setup-python@v2 with: - python-version: 3.x + python-version: "3.9" - name: Install Dev Dependencies run: | diff --git a/docs/conf.py b/docs/conf.py index 5637831a..cedbdc04 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -67,20 +67,21 @@ html_static_path = ["_static"] # sphinx-quickstart --project "docker-stacks" --author "Project Jupyter" -v "latest" -r "latest" -l en --no-sep --no-makefile --no-batchfile # These are custom options for this project +html_theme = "sphinx_book_theme" +html_title = "Docker Stacks documentation" +html_logo = "_static/jupyter-logo.svg" +html_theme_options = { + "path_to_docs": "docs", + "repository_url": "https://github.com/jupyter/docker-stacks", + "use_edit_page_button": True, + "use_issues_button": True, + "use_repository_button": True, + "use_download_button": True, +} + extensions = ["myst_parser", "sphinx_copybutton"] source_suffix = { ".rst": "restructuredtext", ".md": "markdown", } pygments_style = "sphinx" - -html_theme_options = { - "description": "Jupyter Docker Stacks", - "fixed_sidebar": False, - "show_relbars": True, - "github_user": "jupyter", - "github_repo": "docker-stacks", - "github_type": "star", - "logo": "jupyter-logo.svg", - "logo_text_align": "left", -} diff --git a/requirements-docs.txt b/requirements-docs.txt index ba6908ee..e96efa53 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -1,3 +1,8 @@ -myst-parser -sphinx -sphinx-copybutton +# ReadTheDocs environment contains old package versions preinstalled +# So, to ensure we have modern packages, we pin minimum versions of the packages we need +docutils>=0.17 +myst-parser>=0.16.1 +sphinx>=4.4.0 +# sphinx-book-theme>=0.2.0 +git+https://github.com/executablebooks/sphinx-book-theme@master#egg=sphinx-book-theme +sphinx-copybutton>=0.4.0 From d763f19d3c853aaea83b0d77a1eaaa562a4ba4fd Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Sun, 6 Feb 2022 14:31:20 +0300 Subject: [PATCH 2/4] Fail make docs on docs warnings --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 4406e785..c192ceae 100644 --- a/Makefile +++ b/Makefile @@ -138,7 +138,7 @@ install-dev-env: ## install libraries required to build images and run tests docs: ## build HTML documentation - sphinx-build docs/ docs/_build/ + sphinx-build -W docs/ docs/_build/ install-docs-env: ## install libraries required to build docs @pip install -r requirements-docs.txt From a517015ccb0d13da5e7a1b98a6654d5d6bf535f6 Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Sun, 6 Feb 2022 23:53:01 +0300 Subject: [PATCH 3/4] Use commit --- requirements-docs.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/requirements-docs.txt b/requirements-docs.txt index e96efa53..6782d343 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -3,6 +3,7 @@ docutils>=0.17 myst-parser>=0.16.1 sphinx>=4.4.0 -# sphinx-book-theme>=0.2.0 -git+https://github.com/executablebooks/sphinx-book-theme@master#egg=sphinx-book-theme +# TODO(asalikhov): switch to release, when it is available +# sphinx-book-theme +git+https://github.com/executablebooks/sphinx-book-theme@910e26be00e74cafbaaaff274de26b95cab1f7a8#egg=sphinx-book-theme sphinx-copybutton>=0.4.0 From 8e0603acd091e50872628e4c22a69ca95aaef381 Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Sun, 6 Feb 2022 23:55:38 +0300 Subject: [PATCH 4/4] Up copybutton --- requirements-docs.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements-docs.txt b/requirements-docs.txt index 6782d343..3eefd616 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -6,4 +6,4 @@ sphinx>=4.4.0 # TODO(asalikhov): switch to release, when it is available # sphinx-book-theme git+https://github.com/executablebooks/sphinx-book-theme@910e26be00e74cafbaaaff274de26b95cab1f7a8#egg=sphinx-book-theme -sphinx-copybutton>=0.4.0 +sphinx-copybutton>=0.5.0