Allennlp: Updates to the docs

[DeNeutoy]

3602 switched our docs from restructured text to markdown, which is a big improvement. However, there are some left over traces of rst formatting in the docstrings. It would be great if we could comb through these and update them.

• [ ] commands
• [x] common
• [ ] data
• [x] interpret
• [x] models
• [x] modules
• [x] nn
• [x] predictors
• [x] tools
• [x] training

How to help

If you're interested in helping out, just do the below steps and send a PR, mentioning this issue with the section you have completed.

Class and Func references

:class: and :func: references need to be changed to relative links. e.g, we previously had:

:class:~allennlp.training.trainer.Trainer, which needs to be updated to a link to a .md file, relative to the allennlp directory structure. So if this reference was in allennlp/modules/encoder_base.py, the correct replacement link would look like:

[Trainer](../training/trainer.md)

External URLS

External URLS need to be switched to the markdown format, e.g [link text](url). I've done a lot of these, but not all of them.

Types in function/class parameters

Types in function parameters now only need to be surrounded by single backticks, rather than two. e.g ``int`` -> int

Adding code examples

For complicated or hard to use code, it would be nice to have some examples added to docstrings using the triple backtick formatting. These will render nicely in our docs.

Admonition

Admonition is a markdown extension which the docs support, which allow fancy rendering of important blocks/notes/warnings in docs.

The syntax for this is:

!!! note
    this is a note

??? note
    this is a note with the main text hidden in a dropdown

Anything relevant, like TODOs, important notes, or just anything that is critical to _not miss_ whilst reading a docstring could use these.

[DeNeutoy]

3642 has done most of the double backtick cleanup for all directories.

[RyoMazda]

I love the documentation style a lot, especially the API part where we can see the source codes for the parameters of the functions and the classes!

I'm wondering if you guys have any plans for making this docs-functionality into a mkdocs plugin or a python package independent of AllenNLP?

If no, am I allowed to take the code like scripts/py2md.py and put it on the public repository of mine (of course I'm gonna refer appropriately in that case)?

[epwalsh]

Hi @RyoMazda, I think at some point it might make sense to pull py2md out into it's own repo, but it's not a priority at the moment.

You can definitely take the code from that script though and put it into your own repo. We use the Apache 2.0 license, which is very liberal.

[RyoMazda]

Hi @epwaish, I understood the situation. Thank you for the response!