Contributor page needs updates after landing stb-related improvements

[damianavila]

We need to update https://pydata-sphinx-theme.readthedocs.io/en/latest/contributing.html, removing commands that are no longer relevant (ie. yarn), sections that are no longer needed (probably "Build the CSS/JS assets") and decide how deep we want to go in the description because we could explain things and the nox and stb level, but we might want to also go deeper?? (probably not).

[12rambau]

I'm working on the dark-theme PR (#501) and I recently integrated the latest master to my local branch. Could you explain me how to build a dev environment and the doc locally with the new implementation ?

[jorisvandenbossche]

@12rambau you need to pip install sphinx-theme-builder in your current dev environment, and then you can use stb serve docs/ for testing, or use sbt compile to explicitly compile the css/js assets, and then proceed as you did before.

Or if you are using nox, that will take care of installing sphinx-theme-builder for you when needed, and the nox sessions should still work as they did before.

[jorisvandenbossche]

On a general note, related to the changes from #514, I think it would be useful to add back a requirements.txt or environment.yml file that lists all the dev-related dependencies.
For example, if I want to set up a dev environment with conda that includes all dependencies to be able to work on this theme and make the demo docs (without using the environment nox can create for you, eg if you want to control the sphinx version); that is currently a bit convoluted, as this list of optional dependencies now only lives in pyproject.toml.

[12rambau]

2 small updates :

• its stb compile(instead of the non existing sbt)
• you need to install the cli version of sphinx-theme-builder: pip install sphinx-theme-builder[cli]

[jorisvandenbossche]

Yeah, I am constantly confusing sbt and stb :)

[12rambau]

ok, now if I don't want to serve but just build the doc ? It seems that the make html command doesn't work anymore. Is there another stb trick ?

[12rambau]

I found this one in the github actions of the repository, I assume it will do the trick: sphinx-build -b html docs/ docs/_build/html

[jorisvandenbossche]

If you are using nox, you can also do nox -s docs.

If you want to be able to built the docs manually without using sbt serve, we can also add back the make html if using sphinx-build directly is annoying. It was removed in the stb PR in the idea it won't be needed anymore (see also my comment about it at #514 (comment))

[12rambau]

if only I could use nox it doesn't work on my company system (I think it's linked with conda but I clearly don't want to raise the issue and make them realize that I installed other stuff.
I'm getting back all the libs that are not set in .[dev] and I'll let you know

[12rambau]

I get the following error:

Theme error:
An error happened in rendering the page changelog.
Reason: UndefinedError("'jinja2.environment.TemplateModule object' has no attribute 'head_post'")

Any idea where it could come from ?

[12rambau]

As nothing was working I gave up on my branch, I fork back the project in one of my organization. I tried the nox process but nothing worked either:

I tried the following:

pip install .[dev] 
pre-commit install
nox -s docs

the system answered me with the following error:

Extension error:
Notebook execution failed (exception: Kernel died before replying to kernel_info)
Error in atexit._run_exitfuncs:
Traceback (most recent call last):
  File "/Users/pierrickrambaud/opt/miniconda3/lib/python3.8/site-packages/nbclient/client.py", line 370, in _async_cleanup_kernel
    assert self.km is not None
AssertionError
Command exited with exit code: 2
The server will continue serving the build folder, but the contents being served are no longer in sync with the documentation sources. Please fix the cause of the error above or press Ctrl+C to stop the server.

Could you show me a way to install the lib and build the documentation ? I really would like to push the dark theme

[pradyunsg]

Any idea where it could come from?

The templates have likely changed, and your PR was not changed to adapt. If you're running through sphinx-build, pass a --verbose flag and try again. It'll print a traceback.

[choldgraf]

@12rambau - the error you describe looks like it is actually related to executing the Jupyter notebook in the demo docs - do you see any traceback from that error earlier on in the build process?

And when you say that nox can't work, is that because it's restricted at your company or something?

[12rambau]

@choldgraf I saw you added some stuff to main branch I'll check again on a fresh install if I can manage to start it, maybe you solved everything ;-)

And when you say that nox can't work, is that because it's restricted at your company or something?

exactly, I think nox try to write stuff in a floder where I don't have the rights (e.g. usr/). I'm going to check on my personal computer to see if there are any differences.

[12rambau]

ok so on my personnal computer I manage to execute nox, here is the full traceback of the error:

executing demources... [  8%] demo/demo
dyld[20746]: dyld cache '/System/Library/dyld/dyld_shared_cache_x86_64h' not loaded: syscall to map cache into shared region failed
dyld[20746]: Library not loaded: /System/Library/Frameworks/CoreFoundation.framework/Versions/A/CoreFoundation
  Referenced from: /Library/Frameworks/Python.framework/Versions/3.6/Resources/Python.app/Contents/MacOS/Python
  Reason: tried: '/System/Library/Frameworks/CoreFoundation.framework/Versions/A/CoreFoundation' (no such file), '/Library/Frameworks/CoreFoundation.framework/Versions/A/CoreFoundation' (no such file)
sphinx-sitemap warning: No pages generated for sitemap.xml

Extension error:
Notebook execution failed (exception: Kernel died before replying to kernel_info)
Error in atexit._run_exitfuncs:
Traceback (most recent call last):
  File "/Users/pierrickrambaud/Documents/travail/FAO/app_buffer/pydata-sphinx-theme/pydata-sphinx-theme/.nox/docs/lib/python3.8/site-packages/nbclient/client.py", line 370, in _async_cleanup_kernel
    assert self.km is not None
AssertionError

[choldgraf]

I believe that nox will just write things to a local folder (.nox/) I believe.

Your error is related to executing the notebook content in demo/demo. Could you try deleting that page and see if your docs build properly then?