ignite-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dmitry Melnichuk <dmitry.melnic...@nobitlost.com>
Subject Re: Thin Client lib: Python
Date Mon, 02 Jul 2018 18:01:03 GMT
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
> 

Mime
View raw message