2020 DOCUMENTATION REVAMP MASTER ISSUE

[ddavidebor]

The documentation has been a little bit forgotten about.

I have taken in my hands to manage existing PR and issues, then find a way to improve the existing documentation. This may take a long time, and help is needed.

For now, the rough plan is the following:

STAGE 1 (this one is laid out and uncontroversial):

• Cleanup the issues
• Validate PR and merge into develop
• Ask Frappe team to merge PR I am not qualified to work on
• Improve https://github.com/frappe/frappe_docker documentation to cover unattended installs
• Prepare an unattended install script in https://github.com/frappe/frappe_docker
• Setup automated CI builds here, and document build
• Cleanup and fix broken links
• Automatically test broken links in CI
• Verify optimization of images
• Merge develop to master

At the end of STAGE 1, frappe documentation should be better maintained and maintainable.

STAGE 2 (still to be discussed - very hypothetical - you're welcome to propose changes):

• Frappe team is not going to like this... Convert documentation from Frappe to Sphinx... keep reading why
• Fix ToC and hierarchical structure of the documentation so it's more logical
• Creating two sister PR. One adds all the frappe python API documentation into the frappe repository itself through python strings. The second one deletes such documentation from the docs.
• Integrate Sphinx autodoc to automatically generate frappe python API documentation
• write new pages highlighting the interesting functions that were previously manually documented
• Conduct an analysis of existing page and verify what links get broken. Create redirects as needed.
• If frappe teams want coherent UI, someone from the frontend team should create an ad-hoc sphinx theme
• Get frappe to serve the static HTML of the documentation
• Move documentation to the frappe repo.
• find a way to build and deploy from frappe repo
• merge to master

At the end of stage 2 documentation is truly maininable. Python API is built automatically, and code can be documented in a couple of minutes wherever the typical "How can i do XXX" issues arises in the forum. Documentation can be written and built very quickly thanks to Sphinx. New documentation can now be written linking to python API.

STAGE 3 (still to be discussed - very hypothetical - you're welcome to propose changes):

• Create manual OpenAPI to document frappe REST API. If frappe wants to contribute, this could also be done automatically
• Replace frappe rest documentation with Sphinx-OpenAPI integration
• merge to master

At the end of STAGE 3 REST API is properly documented

STAGE 3 (still to be discussed - very hypothetical - you're welcome to propose changes):

• Create Javascript API documentation with Sphinx
  (...)
• merge to master

At the end of STAGE 4 Javascript API are more easy to document.

STAGE 5:

• eat 1kg of salted caramel icecream

---

A couple of notes on how I work:

• I have the bad habit of writing issues banging my head on the keyboard in a hurry then rewrite them. Please check the last edit on github
• Nothing will be merged to master by me unless approved by the frappe team

[ddavidebor]

So I keep getting tons of notifications about PR in the ERPNext documentation, in which I find tons of stuff that should be in the Frappe documentation, so I am asking myself if it would make sense to merge the documentation? Not ideal, but at least someone would give a flying f about it.

[muniter]

So what's being going on with the sprint, I'm interested on helping out. But I'm a little confused since I see that the documentation is in frappe/frappe_docs. I just submitted a PR frappe/frappe_docs#18 but there's 5 more with helpful changes that have not been merged, sadly.

[ddavidebor]

Closed in favour of frappe/frappe_docs#74