[PATCH 2/6] docs-rst: automatically convert Graphviz and SVG images

[Markus Heiser]

> Am 02.03.2017 um 20:09 schrieb Mauro Carvalho Chehab <mchehab at s-opensource.com>:
...

>> 
>> Yes, its only about "docutils>=0.11" in Sphinx 1.3 dependencies. 
>> In Sphinx 1.5 the error:
>> 
>>  https://github.com/sphinx-doc/sphinx/issues/3212
>> 
>> is fixed:
>> 
>>  https://github.com/tk0miya/sphinx/commit/73663f63672f22304810ce6bb9787490ad250127
>> 
>> But this will never be fixed downwards.
> 
> Crap. This kind of patch should be backported to Sphinx 1.3/1.4,
> or Python's PIP repository should be fixed to require docutils
> version to be either 0.11 or 0.12, if one installs version 1.3
> or 1.4 of Sphinx.
> 
> The way it is, PIP repository is broken!

I leaved a comment at sphinx-doc project:

  https://github.com/sphinx-doc/sphinx/issues/3212#issuecomment-283756374

>> All this is about semantic versioning. If you want to promise your
>> builds, you have to name which versions of dependencies you support.
>> I guess this is nothing new for kernel developers ;)
> 
> No. At the Kernel, we do everything possible to not break APIs.

Sorry I was not precise. I was talking about third tools dependencies
and that this is well handled by the kernel ;)
 
> If this were not the case, you wouldn't be able to run Sphinx 1.5 
> with legacy Kernel versions ;-)

This is what I mean ;)

> 
>> The problem is, that PEP440 defines not only ONE version scheme
>> 
>> """Some hard to read version identifiers are permitted by
>>    this scheme in order to better accommodate the wide range
>>    of versioning practices across existing public and private
>>    Python projects."""
>> 
>> In practice, the python projects use slightly different schemes
>> which not follow one rule like <main>.<compatible feature>.<patch> 
>> From history packaging in Python is the hell, it becomes better, but
>> the problem with slightly different version schemes still exist.
> 
> IMHO, the way Python and python libraries break compatibility is crazy.
> 
> Good packaging sense says that, if APIs can break on every single new
> release (with seems to be the case of docutils), then a package
> depending on such bad-developed library should require the exact
> version(s) it is known to work.

I can only repeat myself, the main problem is, that PEP440 allows
multiple version schemes. Instead of one scheme 

 <main>.<compatible feature>.<patch>

Every project use a slightly different scheme and others
do not care about any scheme.

> When we're discussing about the docs toolchain, I mentioned that I
> was afraid that the Python development model would cause this sort
> of issues. Unfortunately, it seems that my concerns were pertinent :-(

Not really ;) .. you are tend to mix at least three parts

1. Python
2. Python packaging
3. Sphinx developers who do not stick there depencies

But you are right, when you say that in all parts some confusion
prevail. E.g.

1. Python 2 to 3 movement has been done reckless
--> in the meantime we have https://pythonhosted.org/six/

2. Python packaging is a mess (setup-tools, distutils, pip, easy_install ..) 
--> in the meantime we have PyPA who brings us more structure (https://www.pypa.io/en/latest)

3. Developer using Python
--> we all have a learn curve and making errors all days long. 
    But this should not stop us from continue :)


>> I guess this is something we should discuss with Jon, he
>> is also familiar with it virtualenv. 
> 
> Yeah, making kernel build to depend on network can be a problem.
> 
> Maybe one way would be to have a sort of "prepare" script that
> would be network-dependent, and will install whatever needed to
> build the docs. If called, make *docs will use the virtualenv.
> Otherwise, it would print a warning message saying that the doc
> build is not reliable, but would try to use whatever installed
> on the machine.

Could be a workaround. May Jon has continuative ideas, nothing
we have to solve today ... give Jon some time.
 
-- Markus --