Allow optional doc themes #2170

happz · 2023-06-26T08:16:57Z

There was already some optionality, PR makes it a bit cleaner to add custom themes for experimenting without way too many nested try/except blocks.

LecrisUT · 2023-06-28T22:49:09Z

Confused as to what this one is for? For local builders to build on a preexisting setup? Wouldn't they be using venv?

happz · 2023-06-29T07:07:00Z

Confused as to what this one is for? For local builders to build on a preexisting setup? Wouldn't they be using venv?

They are using venv, but that does not help, something must tell Sphinx to use different theme from my local venv. So venv on its own does not help, and the code was a nested try/except tree that did not look very nice.

But it's a good point, embedding my local theme into upstream was a bad idea, I'll change it to use envvars instead.

LecrisUT · 2023-06-29T07:28:22Z

It is already in docs extra dependencies and it is used as an extension later on, so it should be fine to have that dictate the theme

psss

Looks good, however I was not able to enable custom theme using a variable:

> TMT_DOCS_THEME=renku_sphinx_theme:renku_sphinx_theme make docs
...
hatch run docs:html
make[1]: Entering directory '/home/psss/git/tmt/docs'
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v6.2.1

Theme error:
no theme named 'renku_sphinx_theme' found (missing theme.conf?)

The renku_sphinx_theme python module is installed. Any other steps are needed?

docs/conf.py

LecrisUT · 2023-10-20T09:45:58Z

Looks good, however I was not able to enable custom theme using a variable:
> TMT_DOCS_THEME=renku_sphinx_theme:renku_sphinx_theme make docs
...
hatch run docs:html
make[1]: Entering directory '/home/psss/git/tmt/docs'
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v6.2.1

Theme error:
no theme named 'renku_sphinx_theme' found (missing theme.conf?)
The renku_sphinx_theme python module is installed. Any other steps are needed?

What about TMT_DOCS_THEME=renku-sphinx-theme:renku. I don't know if project name needs to be normalized like in PyPI with _ -> -. Otherwise the html_theme is supposed to be renku according to that package's documentation

martinhoyer · 2023-10-20T09:56:02Z

no theme named 'renku_sphinx_theme' found (missing theme.conf?)

Have you added it as docs environment dependency?

happz · 2023-10-20T09:58:59Z

Looks good, however I was not able to enable custom theme using a variable:
> TMT_DOCS_THEME=renku_sphinx_theme:renku_sphinx_theme make docs
...
hatch run docs:html
make[1]: Entering directory '/home/psss/git/tmt/docs'
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v6.2.1

Theme error:
no theme named 'renku_sphinx_theme' found (missing theme.conf?)
The renku_sphinx_theme python module is installed. Any other steps are needed?
What about TMT_DOCS_THEME=renku-sphinx-theme:renku. I don't know if project name needs to be normalized like in PyPI with _ -> -. Otherwise the html_theme is supposed to be renku according to that package's documentation

TMT_DOCS_THEME=renku_sphinx_theme:renku make docs works for me.

martinhoyer · 2023-10-20T10:27:16Z

What am I doing wrong? (Python 3.12)
TMT_DOCS_THEME=renku_sphinx_theme:renku make docs

Traceback (most recent call last):
  File "/home/mhoyer/.local/share/hatch/env/virtual/tmt/dNBXLz99/docs/lib/python3.12/site-packages/sphinx/config.py", line 358, in eval_config_file
    exec(code, namespace)  # NoQA: S102
    ^^^^^^^^^^^^^^^^^^^^^
  File "/home/mhoyer/repos/tmt/docs/conf.py", line 80, in <module>
    raise tmt.utils.GeneralError(f"Cannot load theme from TMT_DOCS_THEME, '{theme_specs}'.")
tmt.utils.GeneralError: Cannot load theme from TMT_DOCS_THEME, 'renku_sphinx_theme:renku'.

happz · 2023-10-20T10:29:52Z

What am I doing wrong? (Python 3.12) TMT_DOCS_THEME=renku_sphinx_theme:renku make docs

Traceback (most recent call last):
  File "/home/mhoyer/.local/share/hatch/env/virtual/tmt/dNBXLz99/docs/lib/python3.12/site-packages/sphinx/config.py", line 358, in eval_config_file
    exec(code, namespace)  # NoQA: S102
    ^^^^^^^^^^^^^^^^^^^^^
  File "/home/mhoyer/repos/tmt/docs/conf.py", line 80, in <module>
    raise tmt.utils.GeneralError(f"Cannot load theme from TMT_DOCS_THEME, '{theme_specs}'.")
tmt.utils.GeneralError: Cannot load theme from TMT_DOCS_THEME, 'renku_sphinx_theme:renku'.

Did you install the theme? I started with this:

$ /home/happz/.local/share/hatch/env/virtual/tmt/BuhwJjvK/docs/bin/pip install renku-sphinx-theme
...
$ $ TMT_DOCS_THEME=renku_sphinx_theme:renku make docs
rm -rf /home/happz/git/tmt/tmp build dist tmt.1
rm -rf .cache .mypy_cache .ruff_cache
rm -rf docs/{_build,stories,spec}
find . -type f -name "*.py[co]" -delete
find . -type f -name "*,cover" -delete
find . -type d -name "__pycache__" -delete
find . -type d -name .pytest_cache -exec rm -rv {} +
rm -f .coverage tags
rm -rf examples/convert/{main.fmf,test.md,Manual} Manual
rm -f tests/full/repo_copy.tgz
hatch run docs:html
make[1]: Entering directory '/home/happz/git/tmt/docs'
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v6.2.1
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 21 source files that are out of date
updating environment: [new config] 21 added, 0 changed, 0 removed
reading sources... [100%] stories/install                                                                                                                                                    
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] stories/install                                                                                                                                                     
generating indices... genindex py-modindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in _build/html.

Build finished. The HTML pages are in _build/html.
make[1]: Leaving directory '/home/happz/git/tmt/docs'

martinhoyer · 2023-10-20T10:43:09Z

Did you install the theme? I started with this:

Turns out it has to be in [tool.hatch.envs.docs], not tmt[docs] for this.

happz · 2023-10-20T10:45:48Z

Did you install the theme? I started with this:

Turns out it has to be in [tool.hatch.envs.docs], not tmt[docs] for this.

I don't follow. Do I need to fix anything in my PR?

LecrisUT · 2023-10-20T11:06:31Z

Hatch uses its own environment orthogonal to venv, requiring a different pip install if I understand these correctly

tmt/pyproject.toml

Lines 155 to 157 in cf5e7bf

    
           [tool.hatch.envs.docs] 
        
           dependencies = ["tmt[docs]"] 
        
           detached = true

and that is what is used in the make file:

tmt/Makefile

Lines 42 to 43 in cf5e7bf

    
           docs: clean  ## Build documentation 
        
           	hatch run docs:html

I usually prefer to run the codes manually so that I understand it better and have more control of the options. I also generally use sphinx-autobuild for this and make it as a pycharm configuration. If you guys want I can distribute some of these.

martinhoyer · 2023-10-20T11:07:20Z

Did you install the theme? I started with this:

Turns out it has to be in [tool.hatch.envs.docs], not tmt[docs] for this.

I don't follow. Do I need to fix anything in my PR?

nono, just saying why it didn't work for me. Theme wasn't installed in the docs environment.

fwiw, I really like https://sphinxawesome.xyz/ theme

happz · 2023-10-20T11:36:21Z

Hatch uses its own environment orthogonal to venv, requiring a different pip install if I understand these correctly

True, AFAICT, but since hatch entered our realms, I for one have no virtual environment of my own for tmt, and I rely on hatch to manage them.

I also generally use sphinx-autobuild for this and make it as a pycharm configuration. If you guys want I can distribute some of these.

Feel free to do so, please. I tried to start with sphinx-autodoc, since we're in the area, in #2114 (needs rebase & resurrection).

psss · 2023-10-20T11:52:49Z

TMT_DOCS_THEME=renku_sphinx_theme:renku make docs works for me.

Ah, I see, so I had the wrong name, now works fine. Thanks for clarification.

happz · 2023-10-20T12:07:43Z

fwiw, I really like https://sphinxawesome.xyz/ theme

Yep, that's one of my favorites as well, and the Renku doesn't look bad either.

psss

Thanks for addressing all comments, I just propose a shorter heading and code block in e30045e.

README.rst

psss · 2023-10-20T13:20:25Z

fwiw, I really like https://sphinxawesome.xyz/ theme

Yeah, looks good. However, the On this page navigation on the right side does not work for me when the list is longer than the window height. I can't move it without going the very end of the page.

Yep, that's one of my favorites as well, and the Renku doesn't look bad either.

I have to admit that renku caught my eye. Perhaps, I even wouldn't be against trying to switch the theme :)

happz · 2023-10-20T13:26:52Z

fwiw, I really like https://sphinxawesome.xyz/ theme

Yeah, looks good. However, the On this page navigation on the right side does not work for me when the list is longer than the window height. I can't move it without going the very end of the page.

Yep, that's one of my favorites as well, and the Renku doesn't look bad either.

I have to admit that renku caught my eye. Perhaps, I even wouldn't be against trying to switch the theme :)

I noticed some issues with how specification was rendered in some themes, missing levels - not content, just levels in the left sidebar. Switching from RTD theme would be nice, although right now I am motivated by my own personal profit rather than forcing tmt project to switch - I don't like the RTD theme, there are better ones, and I often consult locally rendered tmt docs, why not enjoy it while reading? :)

I'll be using Renku then, let's see :)

There was already some optionality, PR makes it a bit cleaner to add custom themes for experimenting without way too many nested `try/except` blocks.

LecrisUT · 2023-10-20T14:30:35Z

noticed some issues with how specification was rendered in some themes, missing levels - not content, just levels in the left sidebar. Switching from RTD theme would be nice, although right now I am motivated by my own personal profit rather than forcing tmt project to switch - I don't like the RTD theme, there are better ones, and I often consult locally rendered tmt docs, why not enjoy it while reading? :)

Indeed some sphinx themes are not fully compatible with each other, and some do not render clearly. It would be nice to use this and generate a few variants and pick out which ones are better formatted. For me furo and pydata are promising, but I do not have enough experience with the themes to figure out which ones can render complex structures like the specification pages nicely. Do we have good example pages to use to compare the different themes?

martinhoyer · 2023-10-20T19:18:37Z

I have to admit that renku caught my eye. Perhaps, I even wouldn't be against trying to switch the theme :)

I've found where I saved the themes I liked - this one was not mentioned yet here: https://shibuya.lepture.com/

psss · 2023-10-20T19:44:23Z

/packit build

happz added documentation Improvements or additions to documentation no functional change "No Functional Change" intended. Patch should not change tmt's behavior in any way. labels Jun 26, 2023

happz added this to the 1.26 milestone Jun 26, 2023

happz requested review from psss, lukaszachy and thrix as code owners June 26, 2023 08:16

happz marked this pull request as draft June 29, 2023 07:04

happz modified the milestones: 1.26, 1.27 Jul 24, 2023

happz force-pushed the docs-optional-themes branch from b6d3029 to 5e41671 Compare September 22, 2023 14:05

happz added this to the 1.29 milestone Sep 22, 2023

happz marked this pull request as ready for review September 22, 2023 14:05

thrix requested review from janhavlin and martinhoyer October 10, 2023 08:48

happz force-pushed the docs-optional-themes branch from 5e41671 to 3160047 Compare October 10, 2023 09:27

psss requested changes Oct 20, 2023

View reviewed changes

docs/conf.py Outdated Show resolved Hide resolved

docs/conf.py Show resolved Hide resolved

happz force-pushed the docs-optional-themes branch from 3160047 to 88497cc Compare October 20, 2023 10:10

psss self-assigned this Oct 20, 2023

psss approved these changes Oct 20, 2023

View reviewed changes

LecrisUT reviewed Oct 20, 2023

View reviewed changes

README.rst Outdated Show resolved Hide resolved

psss force-pushed the docs-optional-themes branch from dad9e4c to 636064d Compare October 20, 2023 13:58

Allow optional doc themes

3737c37

There was already some optionality, PR makes it a bit cleaner to add custom themes for experimenting without way too many nested `try/except` blocks.

psss force-pushed the docs-optional-themes branch from 636064d to 3737c37 Compare October 20, 2023 14:08

psss merged commit 3737c37 into main Oct 20, 2023
14 of 16 checks passed

psss deleted the docs-optional-themes branch October 20, 2023 20:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Allow optional doc themes #2170

Allow optional doc themes #2170

happz commented Jun 26, 2023

LecrisUT commented Jun 28, 2023

happz commented Jun 29, 2023

LecrisUT commented Jun 29, 2023

psss left a comment

LecrisUT commented Oct 20, 2023

martinhoyer commented Oct 20, 2023

happz commented Oct 20, 2023

martinhoyer commented Oct 20, 2023

happz commented Oct 20, 2023

martinhoyer commented Oct 20, 2023

happz commented Oct 20, 2023

LecrisUT commented Oct 20, 2023 •

edited

martinhoyer commented Oct 20, 2023

happz commented Oct 20, 2023

psss commented Oct 20, 2023

happz commented Oct 20, 2023

psss left a comment

psss commented Oct 20, 2023

happz commented Oct 20, 2023 •

edited

LecrisUT commented Oct 20, 2023

martinhoyer commented Oct 20, 2023

psss commented Oct 20, 2023

Allow optional doc themes #2170

Allow optional doc themes #2170

Conversation

happz commented Jun 26, 2023

LecrisUT commented Jun 28, 2023

happz commented Jun 29, 2023

LecrisUT commented Jun 29, 2023

psss left a comment

Choose a reason for hiding this comment

LecrisUT commented Oct 20, 2023

martinhoyer commented Oct 20, 2023

happz commented Oct 20, 2023

martinhoyer commented Oct 20, 2023

happz commented Oct 20, 2023

martinhoyer commented Oct 20, 2023

happz commented Oct 20, 2023

LecrisUT commented Oct 20, 2023 • edited

martinhoyer commented Oct 20, 2023

happz commented Oct 20, 2023

psss commented Oct 20, 2023

happz commented Oct 20, 2023

psss left a comment

Choose a reason for hiding this comment

psss commented Oct 20, 2023

happz commented Oct 20, 2023 • edited

LecrisUT commented Oct 20, 2023

martinhoyer commented Oct 20, 2023

psss commented Oct 20, 2023

LecrisUT commented Oct 20, 2023 •

edited

happz commented Oct 20, 2023 •

edited