Conda-forge.github.io: [docs] try out pydata-sphinx-theme?

[bollwyvl]

hey folks! I end up coming to the docs a fair amount (though often not soon enough, usually). It would be lovely if the docs were a little bit nicer on the eyes... recently, I've been trending towards (and contributing to) pydata-sphinx-theme.

There are lots of knobs to turn, but with a little bit of hackery, it could be something like this:

• desktop
  
  
  
  • 
  
  
• mobile
  
  
  
  • 
  
  

Under the hood, it's all the same stuff, and so the search wouldn't be much better... might be worth just delegating out to a custom google/ddg, as the meeting minutes end up crushing everything.

[SylvainCorlay]

The classic rtd theme helps funding rtd with the ads that are displayed.

[xhochy]

@bollwyvl Thanks for looking into this. I personally also prefer the pydata-sphinx-theme over the current one but not so strongly that I would invest like you do.

Splitting of the meeting minutes into a separate sounds like a good idea. Maybe we can just make them a second Sphinx site?

The classic rtd theme helps funding rtd with the ads that are displayed.

We neither use the rtd theme nor RTD for hosting.

[ocefpaf]

Splitting of the meeting minutes into a separate sounds like a good idea. Maybe we can just make them a second Sphinx site?

+1 to that. This has been raised a few times. The current setup makes it really hard to search the docs b/c the returns are mostly the meeting minutes.

[bollwyvl]

Welp, I'll raise the stuff about minutes in a separate issue... didn't know I would strike a chord there!

[viniciusdc]

@xhochy what's the actual status of this issue in your opinion, haven't we solved it?

[xhochy]

No, we still not using the pydata-sphinx-theme and it would be nice to try it out. So this is definitely no solved yet.

[bollwyvl]

Should have the branch around someplace... will get it back into shape and PR for the lookin... also somewhere along the way got maintainer rights over there :grimacing: so if we need anything...

[bollwyvl]

ugh, some stuff got broken weird...

Theme error:
An error happened in rendering the page orga/minutes/2018-08-07.
Reason: AttributeError("'NoneType' object has no attribute 'get'")
make: *** [Makefile:58: html] Error 2

probably need to start over :pouting_cat:

[bollwyvl]

Oy, just changing to theme = "pydata_sphinx_theme" yields:

/home/weg/projects/conda-forge/conda-forge.github.io_/conda-forge.github.io/src/README.md:3: WARNING: None:any reference target not found: ../ci_scripts/update_docs

Theme error:
An error happened in rendering the page README.
Reason: TypeError("make_toctree() got an unexpected keyword argument 'titles_only'")
make: *** [Makefile:58: html] Error 2

[TinoMako]

Oy, just changing to theme = "pydata_sphinx_theme" yields:

/home/weg/projects/conda-forge/conda-forge.github.io_/conda-forge.github.io/src/README.md:3: WARNING: None:any reference target not found: ../ci_scripts/update_docs

Theme error:
An error happened in rendering the page README.
Reason: TypeError("make_toctree() got an unexpected keyword argument 'titles_only'")
make: *** [Makefile:58: html] Error 2

Hello, this issue sparked my interest. I have been looking for ways to change the theme to no avail, is there anything l can do to help or maybe suggest some resources l can use to change the theme. l tried (conda install -c conda-forge pydata-sphinx-theme) on my computer then followed a couple of tutorials then l got lost in the woods.
-Total Newbie

[bollwyvl]

@tinomako Sorry, for context:

ways to change the theme

Do you mean on _this_ repo, or in general? If the latter, check the upstream docs example for a starting point. If the former... this one has accrued rather a lot of "specialness," (as most sphinx builds eventually do) and it will take some doing to untangle to make a big change like a theme....

[TinoMako]

Ohh l understand now, l meant the former. Thank you for the response.

[bollwyvl]

Yeah... so if I was trying to update this build and add some modern components, I'd probably:

• port the entire rst codebase over to md and use myst
• get rid of a number of seemingly-unsupported extensions, try to replace them with better-supported ones
  
  
  
  • though there doesn't seem to _be_ a well-supportd RSS one :crying_cat_face:
  
  
• clean up the stuff hidden inside the CI scripts so that it was just the traditional make html
  
  
  
  • if there is _heavy_ prebuild stuff, move it to doit
  
  
• add sphinx-autobuild for local watching
• _then_ try to make theme changes!

[TinoMako]

I am a total noob but this really got me interested, l am not acquainted with some(maybe most of the stuff) but this is something l would love to take on for a challenge and also familiarize myself with the codebase. Some of the stuff is way over my head, do you have any articles, tutorials, or anything that could help me to do this? Thank you again for the response.

[bollwyvl]

Unfortunately, _large documentation site management with sphinx_ is a thing people get working, and then try to avoid thinking about. This is definitely one of those cases where you find something that someone else got working, and go with it. A place to start is the ~200 repos that currently have pydata_sphinx_theme in there conf.py. Let the cargo-culting begin!