Hi! (please excuse the chaotic style - I basically re-wrote my IRC messages into an e-mail)
I'm thinking of implementing a Sphinx extension, but first wanted to make sure I'm not duplicating effort. It would be a variant of sphinx.ext.todo but with multiple topics - something that would allow the user to mix documentation and code via sphinx.ext.autodoc, having Sphinx reassemble it to per-topic pages. Right now when you're writing sphinx documentation, you basically have two realms: the actual documentation and API reference. They don't seem intersect much, which feels like a wasted opportunity to me. Instead, imagine being able to put in your source code something like: .. about topic=topicName ...and then add some content, which is going to end up under a new documentation page as a bullet list. My idea is inspired by literate programming - I feel that it would allow the developer to avoid duplicating pieces of information and keep the code and its documentation in sync. So far I spent some time searching the web and found nothing similar - there's sphinx-litprog [1], but it feels backwards - I'd like to embed documentation in code, not the other way round. Assuming that sphinx.ext.todo can be put in sphinx.ext.autodoc, I think that I should be able to land a proof of concept relatively quickly, but the ultimate result I'd like to achieve is something a bit further from bullet lists. Instead, I'd prefer having paragraphs and a bit of control about how they're ordered. For example, I'd like to be able to name notes and say things like "let's call this note B. it should be placed between note B and C", or "this note should be put somewhere in the beginning/end of that topic page". What do you think? Does the idea sound clear enough? Does it sound like something that was already tried? If not, could it be because there's some fundamental flaw in it? It sounds like a tool that would be useful to me, but perhaps there's something major that I'm missing. Cheers, d33tah [1] https://sphinx-litprog.readthedocs.io/en/stable/ -- You received this message because you are subscribed to the Google Groups "sphinx-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/5a07760f-8f36-47ac-9773-ae1734291189n%40googlegroups.com.
