[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!

[ForgottenProgramme]

@viniciusdc What do you think about this now?

[viniciusdc]

@viniciusdc What do you think about this now?

Definitely I think that if we have a new preview of how those changes might be, it would be wonderful.. and I think @bollwyvl has already addressed some of the most outstanding features/steps necessary for such a change.

But, even if we can achieve a new layout (maybe changing the color schema later on) we still need to check if it's practical to implement or not...

• As commented above, the RSS feed is "something" with an outstanding usage within the docs, so have that working would be essential when switching dependencies.

  port the entire rst codebase over to md and use myst

• In my opinion this might be optional, but I would love to use markdown instead of rst

  clean up the stuff hidden inside the CI...

• this part might not be difficult, we should only be carefull with some of the old manual additions that were inserted in the actions…

So… I think we need to make a draft about the benefits vs the difficulties in switching things , as well promote this with a doc preview, almost like a demo…

[viniciusdc]

Funny consequence, we could then merge the Blog under some special section of the new Docs. With the same theme and maybe using only one source of things...