This week was mainly spent on writing docstrings to improve the overall documentation of the project. My goal was to get the API reference up to date with the work I've done and get it hosted via ReadTheDocs. However, there were a couple of hiccups on the way, hence I am devoting this blog post to ReadTheDocs.
ReadTheDocs makes parsing docstrings and hosting documentation a lot easier than having to do it manually, however their documentation is a bit unfriendly towards first time users. Like if you want to use an Automatic Docstring parser to parse docstrings, a user will have to install recommonmark but a simple pip install wont work. After some docs hunting I found out that one needed to add this function to the configuration file.
I hope this code snippet helps others in automating their documentation pipeline. I am also sure that the authors of these packages will fix these issues within the near future. Long live Open Source Software.
ReadTheDocs makes parsing docstrings and hosting documentation a lot easier than having to do it manually, however their documentation is a bit unfriendly towards first time users. Like if you want to use an Automatic Docstring parser to parse docstrings, a user will have to install recommonmark but a simple pip install wont work. After some docs hunting I found out that one needed to add this function to the configuration file.
from recommonmark.transform import AutoStructify
...
github_doc_root = "https://github.com/rtfd/recommonmark/tree/master/doc/"
def setup(app):
app.add_config_value(
"recommonmark_config",
{
"url_resolver": lambda url: github_doc_root + url,
"auto_toc_tree_section": "Contents",
},
True,
)
app.add_transform(AutoStructify)
I hope this code snippet helps others in automating their documentation pipeline. I am also sure that the authors of these packages will fix these issues within the near future. Long live Open Source Software.