olcf/olcf-user-docs

build: missing tabbed directive type

naughtont3 opened this issue · 6 comments

naughtont3 commented

When trying to build the documentation using Python-3.11 (macOS-13.6.1) I get errors about the "tabbed" directive, e.g.,
ERROR: Unknown directive type "tabbed".. The resulting HTML files do not show the tabbed items on the page.

For example, the User Managed Software page does not show Frontier and Crusher tabs (the block is not rendered) when viewed offline in browser.

Steps to reproduce issue:

shell:$ git clone git@github.com:olcf/olcf-user-docs.git
shell:$ cd olcf-users-docs/
shell:$ python3 -V
Python 3.11.5
shell:$ python3 -m venv venv3.11
 ...<snip>...
shell:$ source venv3.11/bin/activate
(venv3.11) shell:$ pip install --upgrade pip
  ...<snip>...
(venv3.11) shell:$ pip3 install sphinx sphinx_rtd_theme sphinx-panels jinja    2==3.0 docutils==0.17.1
  ...<snip>...
(venv3.11) shell:$ make html
Running Sphinx v5.3.0
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 128 source files that are out of date
updating environment: 6 added, 2 changed, 0 removed
reading sources... 
[ 37%] venv3.11/lib/python3.11/site-packages/Jinja2-3.0.0.disreading sources... 
[ 50%] venv3.11/lib/python3.11/site-packages/MarkupSafe-2.1.3reading sources... 
[ 62%] venv3.11/lib/python3.11/site-packages/imagesize-1.4.1.reading sources... 
[ 75%] venv3.11/lib/python3.11/site-packages/sphinx/ext/autosreading sources... 
[ 87%] venv3.11/lib/python3.11/site-packages/sphinx/ext/autosreading sources... 
[100%] venv3.11/lib/python3.11/site-packages/sphinx/ext/autosummary/templates/autosummary/module
/Users/3t4/projects/olcf/olcf-user-docs/software/UMS/index.rst:27: ERROR: Unknown directive type "tabbed".

.. tabbed:: Frontier

 ...<snip>...

build succeeded, 30 warnings.

The HTML pages are in _build/html.
(venv3.11) shell:$

Versions of the packages in virtual env:

(venv3.11) shell:$ pip freeze 
alabaster==0.7.13
Babel==2.13.1
certifi==2023.11.17
charset-normalizer==3.3.2
docutils==0.17.1
idna==3.6
imagesize==1.4.1
Jinja2==3.0.0
MarkupSafe==2.1.3
packaging==23.2
Pygments==2.17.2
requests==2.31.0
snowballstemmer==2.2.0
Sphinx==5.3.0
sphinx-panels==0.4.1
sphinx-rtd-theme==2.0.0
sphinxcontrib-applehelp==1.0.7
sphinxcontrib-devhelp==1.0.5
sphinxcontrib-htmlhelp==2.0.4
sphinxcontrib-jquery==4.1
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.6
sphinxcontrib-serializinghtml==1.1.9
urllib3==2.1.0
(venv3.11) shell:$
naughtont3 commented

Note, I was using build guidelines from this URL.

naughtont3 commented

@chrisfuson Can you share a list of pkgs (requirements.txt) you use in a working build environment?
(something like pip freeze > requirements.txt inside your venv)

michael-sandoval commented

@naughtont3 We're in the process of seeing if we can get around calling out specific version packages in general (like Jinja2 and docutils), but for now, you can get around this by installing sphinx-panels==0.6.0. So, in your pip install line:

pip3 install sphinx sphinx_rtd_theme sphinx-panels==0.6.0 jinja2==3.0 docutils==0.17.1

The newest version of sphinx that pip automatically finds doesn't work with newer versions of sphinx-panels yet, so it downgrades the sphinx-panels version enough where the tabbed directive doesn't exist anymore.

  • 👍1
michael-sandoval commented

Fixing in PR #752

  • 👍1
naughtont3 commented

Thanks @michael-sandoval the above sphinx-panels==0.6.0 allowed me to build to check my edits. There were still some other unrecognized directives, but not in the places I was touching.

michael-sandoval commented

@naughtont3 No problem! Yup, as of now, there's about 8 warnings that are fine overall (some in the data section, and other titles not being underlined enough). I plan to clean up the underlines soon, but the data warnings are legacy pages we keep around.

  • 👍1