search

allenai / deep_qa

A deep NLP library, based on Keras / tf, focused on question answering (but useful for other NLP too)
Apache License 2.0
404 stars 132 forks source link

[WIP] possible way to get READMEs into docs #376

Open DeNeutoy opened 7 years ago

DeNeutoy commented 7 years ago

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.

DeNeutoy commented 7 years ago

@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?

nelson-liu commented 7 years ago

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

nelson-liu commented 7 years ago

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

DeNeutoy commented 7 years ago

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!

matt-gardner commented 7 years ago

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.

matt-gardner commented 7 years ago

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).