Hi Igor,
I totally agree with the point that auto-generated things does not
belong to the source tree.
I already made short instructions on how to generate HTML documents with
Sphinx in README file. The instructions assume that the user is able to
use the common tools (Python, pip, virtualenv) and have them installed.
From the beginning of the development we found it inconvenient for
those who wish to just read the documents and not fire up the whole
development process. That's why I included the prebuilt documents in the
repository.
Note also, that Python programs, unlike Java ones, do not have the
additional build step and always distributed as text. So each user will
have to build the documents from the source to read it.
To leverage this condition, most of Python package developers use
readthedocs.org service (freemium, engine is under MIT license) to
publish their documentation online. Unfortunately, the service can not
be used by our project because of the directory structure. RTD treats
the git root as a home to `docs` directory to build Sphinx docs out of
it. In our case it would build anything but the documents we need from
upstream git source. This situation can be fixed by developing Python
thin client in a separate git repository and including it in upstream as
a git sub-module, but I see this solution is too radical.
Anyway, I am removing the prebuilt docs from now on, just as you
suggested. Hope that potential usability problems might be addressed in
the future.
On 07/02/2018 09:41 PM, Igor Sapego wrote:
By the way, guys,
I can see generated docs under source control. We do not store them
this way in Ignite. Instead, we have separate step during release, where
we generate them and include in binary distribution.
So you should remove documents from Git and provide us with instructions
on how to generate docs during release.
Best Regards,
Igor
