deep_qa
deep_qa copied to clipboard
allenai
[WIP] possible way to get READMEs into docs
Here is a possible way to get the .md files in the docs - not ideal to have to convert them and it also means we can't use relative github paths in the .md files, but it seems to work.
I tried doing the way you suggested in #314, but I couldn't get it to recognise the imported .md file - I tried several ways of doing this, including switching index.rst over to a md file.
I wanted to see what you thought initially with this approach before I clean up the links and include more of the readmes in the other directories. It's possibly (probably) easier to just switch to .rst instead of markdown.
@nelson-liu any idea how I can stop this error happening whilst still using html-strict as the build command? Does it even need to be strict?
I think the original thinking behind using html-strict was to make sure our docstrings were parseable.
looks like this isnt a new problem though, and this stackoverflow question seems to have some possible solutions? https://stackoverflow.com/a/28778969/2544124
to be clear, this looks like the relevant thing to add to conf.py
suppress_warnings = ['image.nonlocal_uri']
see: https://github.com/sphinx-doc/sphinx/issues/2466#issuecomment-213211534
Yeah, that doesn't seem to be working: https://github.com/allenai/deep_qa/pull/376/files#diff-684a0ceb2878d48b19612ca360e277efR62.
I'll try that monkey-patch fix, but maybe that's not preferable to just using the non-strict version... Thanks for looking!
For the longer term question, I think it'd be preferable to switch everything (including docstrings) to markdown, instead of RST, we'd just have to figure out how to build the docs correctly in that setting. There are some complicated issues there, though, and it's not super high priority.
For what you've done in this PR, I think this is a great way to get us part of the way there, and at least not duplicate the README files that we have. So, yes, I think this approach is a good idea.
Changed the name of this so it's easier to keep track of what needs to be looked at. When it's ready to be looked at again (or if it already is), change it back (and/or add the "Please Review" label).