I already know this is a very noobish question, but I'm having some doubts on how to write docs for a project I'm working on. Basically I built an API using Django and now I need to write Docs for it, so i got started to Sphinx and I got started, so I created my first documentation and built the HTML for it with the command make html.
Now, I understand that in order to writing docs I need to work with rst files, but I'm very new to it and I still have to fully understand how does its syntax work, so my question is: Why can't I just take the HTML generated by Sphinx and keep writing the documentation on the HTML files, instead of using reST and make html every time?
Is it an advantage that I'll see once I'm more familiar with reST? And is it still fine if I just grab the template generated by Sphinx and build the documentation on the same HTML files?
Lets start by addressing one key difference:
difference between using reST and using HTML
Both reST and HTML are markup languages, however reST is more light-weight than HTML. Notice that in HTML elements are surrounded by tags and everything is explicit. While in reST the syntax is less convoluted, resulting in better plain text legibility and maintainability. Given 2 constructs in both languages, the reST construct will be more concise by relying on implicit rules like indentation.
reStructuredText Markup Specification
Simple, implicit markup is used to indicate special constructs (...) The markup used is as minimal and unobtrusive as possible.
Then lets think about one key goal of reStructured text:
The primary goal of reStructuredText is to define and implement a markup syntax for use in Python docstrings (...) that is readable and simple, yet powerful enough for non-trivial use. The intended purpose of the markup is the conversion of reStructuredText documents into useful structured data formats.
This is consistent with Docstring Format Goals - PEP 216.
Now we have some context to answer the full question in the title:
What's the difference between using reST and using HTML to write documentation with Sphinx?
In simple technical terms, you can include HTML in a reST file for Sphinx to generate the final documentation. This is possible by using a number of reST directives, like meta, include or raw. But by doing so you are loosing out on the previsouly mentioned reST advantages.
Additionally, Sphinx has a number of builders available to generate different output formats. By using HTML over reST you loose the transparency of generating to those formats.
Why can't I just take the HTML generated by Sphinx and keep writing the documentation on the HTML files?
Because editing the final HTML would be cumbersome and tedious, you would have to maintain a number of Sphinx functionalities by hand, like cross-references, an index, and interoperability with a wide array of domains.
Automation and productivity are a hallmark advantage of reST and Sphinx. E.g. Their use abstracts from editing HTML attributes and all other HTML elements are transparently generated and their consistency is managed by Sphinx for you.