deep_qa
deep_qa copied to clipboard
Make docs incorporate READMEs
We have a few places under doc/
where we've written explanations of things. Those explanations really should be in READMEs in the code, and just read from the README and put into doc/
, instead of duplicated in both places.
I don't know if this is easy or hard, because I don't know enough about how sphinx works, or how ReadTheDocs actually builds our docs for each commit. It's probably hard.
This is probably not too hard. Here's an example of how scikit-learn does it:
- There's an
about.rst
in thedoc/
directory- If you look at the raw source of that rst, note the
.. include:: ../AUTHORS.rst
. This basically tells sphinx "ok, go to that path, take all the stuff in that RST file and put it in here"
- If you look at the raw source of that rst, note the
- Then, the final generated doc looks like this. Note that the contents of
AUTHORS.rst
have been inserted
Nice, thanks Nelson! It probably means that we'd need to move to RST instead of markdown everywhere, though... I was hoping to go the other way, but I could live with it if it gives us nicer docs.
There might be a way to combine the two: https://github.com/sphinx-doc/sphinx/issues/2840#issuecomment-284863143.