[Proposal] Documentation - Lets start Google style with sphinx.napoleon

Hey awesome ppl,

A big problem with ERPnext is the luck of documentation and guidelines for that.
I am here to make it easy … (kidding) …

So my proposal is from now on everything should be has a docstring using Google Style and using sphinx.napoleon for auto-docs creations.

Check the example here: http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html#example-google

I proposing this to be a official ERPnext guideline for all merge requests from now on…

3 Likes

@kickapoo thanks for taking leadership :smile:

The built in ERPNext documentation is sphinx like. Any major issues with that?

https://frappe.github.io/frappe/user/en/guides/app-development/generating-docs

Example docs:

https://frappe.github.io/frappe/current/api/frappe.init

hey @rmehta,

I know you have this awesome feature and to answers your question I will quote from napoleon documentation.

ReStructuredText is great, but it creates visually dense, hard to read docstrings. Compare the jumble above to the same thing rewritten according to the Google Python Style Guide:

This where my proposal stands. The readability of the doc strings :slight_smile:

We don’t use ReST, we use Markdown :wink:

I can’t answer the question if the current system works or if sphinx would bring benefits but in general I think it’s an important point to put this in our developer guidelines and on the merge request checklist.

I am used to JavaDoc and its enforced structure. In our IDE when programming java incorrect JavaDoc would actually be configured to lead to a build error. Could Travis fire warnings when properly structured and complete docstrings are missing?

I was trying to make the point of readability … :slight_smile: . Also, i think is most more attractive is say we are using Google python doc guidelines

So, the question is, should we create a basic example_doc.py to expose the ERPnext guidelines … for example frappe.init.py has no Returns docs.

@kickapoo yeah suggest a few changes via a small pull request