Ideas to re-use the references/ folder in other documentation

[choldgraf]

I love the reference section of Furo. It both covers a lot of great content, is easier to navigate than many "kitchen sink" style references, and does a great job of highlighting both rST and MyST.

I liked it so much that I even tried to get it running on the Sphinx Book Theme, you can find a PR for that here: executablebooks/sphinx-book-theme#353

That PR basically:

1. Downloads a ZIP of Furo's repository, and extracts all the files under reference into a directory in our docs
2. Installs furo and activates furo.sphinxext in our conf.py

I ran into some issues which made it hard (or impossible?) to re-use. Opening this issue to list a few ideas that came up:

• The main issue is that the output doesn't show up - whatever furo-demo outputs seems to be an empty container and I'm not sure why.
• In terms of the content itself, there are two cross-refs that are Furo-specific: admonitions.md:177 and images.md:60
• furo-demo could be a useful extension to include in a more generalizable form for people that want to show multiple syntaxes for the same behavior. I wonder if an easy path forward would be to define a directive like demo-markup that would take its contents, display them as a literal block, and then also display the parsed contents just below so you see how that literal block renders. Then this could be combined with your tabs example and would be similarly flexible and a bit simpler than hard-coding rst/myst structure in furo-demo.

No idea if any of these ideas are actionable, but wanted to share them in case they're of interest to you :-)

[pradyunsg]

How relevant is this still? :)

[choldgraf]

IMO that is totally fine. I think the annoying thing is having errors embedded in like line 273 of 546 so you have to remember to go fishing for them whenever you update 🙂

[choldgraf]

Think about it - it might also be helpful to have this as a dedicated file if only because "handling errors" are kind-of a special case anyway. Perhaps it'd be helpful from a user-facing perspective as well, not just for needy developers like myself?

[pradyunsg]

Yea. Some other weekend tho. :)

[choldgraf]

Would you be open to review a light PR that does this?

[choldgraf]

I decided to just manually check for "unexpected warnings" in our test suite, so for me the need to have a separate errors file is not as strong now. I'm happy to just consider this resolved (even though it's not an issue 🙂)

[pradyunsg]

@choldgraf Anything more actionable here? We have the same content being shared across a bunch of themes IIUC. Should I make this a part of sphinx-theme-builder somehow, to allow it to synchronise the kitchen sink by manually running a command?

[choldgraf]

I think this is pretty much done, and it is lovely IMO 🙂

Though I keep getting a weird auto summary error about kissing urllib stub files i haven't been able to debug..have you run into that?

[choldgraf]

I do really like the "synchronize by running a command" idea... I wouldn't make it too complex, maybe just a one liner to download all of the latest versions?

[pradyunsg]

Do you have links to the code you're using for this right now?

[choldgraf]

• our kitchen sink: https://github.com/pydata/pydata-sphinx-theme/tree/main/docs/examples/kitchen-sink
• index file: https://github.com/pydata/pydata-sphinx-theme/blob/main/docs/examples/kitchen-sink/index.rst
• and example action warnings: https://github.com/pydata/pydata-sphinx-theme/runs/7591218373?check_suite_focus=true#step:6:58

[choldgraf]

Ah and the script to download it: https://github.com/pydata/pydata-sphinx-theme/blob/main/docs/scripts/update_kitchen_sink.py

[pradyunsg]

I'm gonna mark this as "answered", based on #181 (reply in thread).