A docs team in another department is currently using sphinx + docstrings + rst. they want out of sphinx but it seems pretty sticky. I want to help, I’m not very familiar with that style of docs.
I noticed that Hugo supports .rst which is great, but a lot of the roles like :doc: and :ref: are not supported by vanilla .rst – they are part of sphinx. Looking into it, it sounds like you are able to create custom parsers to replace these, but I have no clue how I could use those with Hugo. Is it possible?
My thoughts are to do this:
- have them continue to write in rst
- build a custom parser that replaces the missing functionality for :doc: and :ref: left behind by sphinx
- update their files to use frontmatter
- ingest their docs collection as a submodule for a hugo site