[ovs-dev] readthedocs: Add the configuration file.

Since last month ReadTheDocs only supports building with a new
configuration file provided in the repository itself:
  https://blog.readthedocs.com/migrate-configuration-v2/

So, all our documentation buids are failing for quite some time.

Add the configuration file to unblock documentation updates.

Need to remove the upper restriction on the sphinx version.
sphinx 2.0 is very old at this point and pip fails to install
it along with other dependencies on the rtd server.

Note: Sphinx 2.0 moved from HTML4 to HTML5 renderer and tables
no longer have borders by default.  That should be addressed
via CSS file in the ovs-sphinx-theme.

Signed-off-by: Ilya Maximets <i.maximets@ovn.org>
---
 .readthedocs.yaml              | 24 ++++++++++++++++++++++++
 Documentation/requirements.txt |  2 +-
 Makefile.am                    |  1 +
 3 files changed, 26 insertions(+), 1 deletion(-)
 create mode 100644 .readthedocs.yaml

On 23.10.23 15:31, Ilya Maximets wrote:
> Since last month ReadTheDocs only supports building with a new
> configuration file provided in the repository itself:
>   https://blog.readthedocs.com/migrate-configuration-v2/
>
> So, all our documentation buids are failing for quite some time.
>
> Add the configuration file to unblock documentation updates.
>
> Need to remove the upper restriction on the sphinx version.
> sphinx 2.0 is very old at this point and pip fails to install
> it along with other dependencies on the rtd server.
>
> Note: Sphinx 2.0 moved from HTML4 to HTML5 renderer and tables
> no longer have borders by default.  That should be addressed
> via CSS file in the ovs-sphinx-theme.

It was initially limited to 2.0 for RHEL7 support [0]. Is this still relevant?

[0] https://github.com/openvswitch/ovs/commit/59cf52e6d3307d5889335893fc941fe55cd3ed99

On 23.10.23 20:52, Jakob Meng wrote:
> On 23.10.23 15:31, Ilya Maximets wrote:
>> Since last month ReadTheDocs only supports building with a new
>> configuration file provided in the repository itself:
>>   https://blog.readthedocs.com/migrate-configuration-v2/
>>
>> So, all our documentation buids are failing for quite some time.
>>
>> Add the configuration file to unblock documentation updates.
>>
>> Need to remove the upper restriction on the sphinx version.
>> sphinx 2.0 is very old at this point and pip fails to install
>> it along with other dependencies on the rtd server.
>>
>> Note: Sphinx 2.0 moved from HTML4 to HTML5 renderer and tables
>> no longer have borders by default.  That should be addressed
>> via CSS file in the ovs-sphinx-theme.
> It was initially limited to 2.0 for RHEL7 support [0]. Is this still relevant?
>
> [0] https://github.com/openvswitch/ovs/commit/59cf52e6d3307d5889335893fc941fe55cd3ed99
>

bs 🙄 This commit [1] introduced the 2.0 limit but its not clear why.

[1] https://github.com/openvswitch/ovs/commit/eeab45ffdc74325ba1aef893b1805e69867789da

On 10/23/23 20:56, Jakob Meng wrote:
> On 23.10.23 20:52, Jakob Meng wrote:
>> On 23.10.23 15:31, Ilya Maximets wrote:
>>> Since last month ReadTheDocs only supports building with a new
>>> configuration file provided in the repository itself:
>>>   https://blog.readthedocs.com/migrate-configuration-v2/
>>>
>>> So, all our documentation buids are failing for quite some time.
>>>
>>> Add the configuration file to unblock documentation updates.
>>>
>>> Need to remove the upper restriction on the sphinx version.
>>> sphinx 2.0 is very old at this point and pip fails to install
>>> it along with other dependencies on the rtd server.
>>>
>>> Note: Sphinx 2.0 moved from HTML4 to HTML5 renderer and tables
>>> no longer have borders by default.  That should be addressed
>>> via CSS file in the ovs-sphinx-theme.
>> It was initially limited to 2.0 for RHEL7 support [0]. Is this still relevant?
>>
>> [0] https://github.com/openvswitch/ovs/commit/59cf52e6d3307d5889335893fc941fe55cd3ed99
>>
> 
> bs 🙄 This commit [1] introduced the 2.0 limit but its not clear why.
> 
> [1] https://github.com/openvswitch/ovs/commit/eeab45ffdc74325ba1aef893b1805e69867789da

The limit was set 2 years prior sphinx 2.0 release, so I'd say it
was just a defensive measure for potential breaking changes in the
future major release.  It would be an equivalent of having <8.0
requirement today.  Sphinx changed their release strategy to having
one major release per year, so I'm not really sure if the limit
like this makes much sense today.  It's probably easier to just
spot the breakage faster and fix it.  We can always limit later
if the breaking change will be too severe to fix right away.

Best regards, Ilya Maximets.

Ilya Maximets <i.maximets@ovn.org> writes:

> Since last month ReadTheDocs only supports building with a new
> configuration file provided in the repository itself:
>   https://blog.readthedocs.com/migrate-configuration-v2/
>
> So, all our documentation buids are failing for quite some time.
>
> Add the configuration file to unblock documentation updates.
>
> Need to remove the upper restriction on the sphinx version.
> sphinx 2.0 is very old at this point and pip fails to install
> it along with other dependencies on the rtd server.
>
> Note: Sphinx 2.0 moved from HTML4 to HTML5 renderer and tables
> no longer have borders by default.  That should be addressed
> via CSS file in the ovs-sphinx-theme.
>
> Signed-off-by: Ilya Maximets <i.maximets@ovn.org>
> ---

Looks like it stopped working about a month ago.  Good future idea for a
bot to monitor this part.

Anyway:

Acked-by: Aaron Conole <aconole@redhat.com>

>  .readthedocs.yaml              | 24 ++++++++++++++++++++++++
>  Documentation/requirements.txt |  2 +-
>  Makefile.am                    |  1 +
>  3 files changed, 26 insertions(+), 1 deletion(-)
>  create mode 100644 .readthedocs.yaml
>
> diff --git a/.readthedocs.yaml b/.readthedocs.yaml
> new file mode 100644
> index 000000000..e481e64f1
> --- /dev/null
> +++ b/.readthedocs.yaml
> @@ -0,0 +1,24 @@
> +# .readthedocs.yaml
> +# Read the Docs configuration file.
> +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details.
> +
> +# Required.
> +version: 2
> +
> +# Set the OS, Python version, etc.
> +build:
> +  os: ubuntu-22.04
> +  tools:
> +    python: "3.12"
> +
> +# Build documentation in the "Documentation/" directory with Sphinx.
> +sphinx:
> +  configuration: Documentation/conf.py
> +
> +# Build all formats: HTML, PDF, ePub.
> +formats: all
> +
> +# Declare the Python requirements.
> +python:
> +  install:
> +  - requirements: Documentation/requirements.txt
> diff --git a/Documentation/requirements.txt b/Documentation/requirements.txt
> index 77130c6e0..77f44bd76 100644
> --- a/Documentation/requirements.txt
> +++ b/Documentation/requirements.txt
> @@ -1,2 +1,2 @@
> -sphinx>=1.1,<2.0
> +sphinx>=1.1
>  ovs_sphinx_theme>=1.0,<1.1
> diff --git a/Makefile.am b/Makefile.am
> index 439e2bf6d..94f488d18 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -84,6 +84,7 @@ EXTRA_DIST = \
>  	.cirrus.yml \
>  	.editorconfig \
>  	.github/workflows/build-and-test.yml \
> +	.readthedocs.yaml \
>  	appveyor.yml \
>  	boot.sh \
>  	poc/builders/Vagrantfile \

On 10/25/23 15:20, Aaron Conole wrote:
> Ilya Maximets <i.maximets@ovn.org> writes:
> 
>> Since last month ReadTheDocs only supports building with a new
>> configuration file provided in the repository itself:
>>   https://blog.readthedocs.com/migrate-configuration-v2/
>>
>> So, all our documentation buids are failing for quite some time.
>>
>> Add the configuration file to unblock documentation updates.
>>
>> Need to remove the upper restriction on the sphinx version.
>> sphinx 2.0 is very old at this point and pip fails to install
>> it along with other dependencies on the rtd server.
>>
>> Note: Sphinx 2.0 moved from HTML4 to HTML5 renderer and tables
>> no longer have borders by default.  That should be addressed
>> via CSS file in the ovs-sphinx-theme.
>>
>> Signed-off-by: Ilya Maximets <i.maximets@ovn.org>
>> ---
> 
> Looks like it stopped working about a month ago.  Good future idea for a
> bot to monitor this part.
> 
> Anyway:
> 
> Acked-by: Aaron Conole <aconole@redhat.com>

Thanks!  Applied.

And the build passed!

Best regards, Ilya Maximets.

On 10/25/23 17:23, Ilya Maximets wrote:
> On 10/25/23 15:20, Aaron Conole wrote:
>> Ilya Maximets <i.maximets@ovn.org> writes:
>>
>>> Since last month ReadTheDocs only supports building with a new
>>> configuration file provided in the repository itself:
>>>   https://blog.readthedocs.com/migrate-configuration-v2/
>>>
>>> So, all our documentation buids are failing for quite some time.
>>>
>>> Add the configuration file to unblock documentation updates.
>>>
>>> Need to remove the upper restriction on the sphinx version.
>>> sphinx 2.0 is very old at this point and pip fails to install
>>> it along with other dependencies on the rtd server.
>>>
>>> Note: Sphinx 2.0 moved from HTML4 to HTML5 renderer and tables
>>> no longer have borders by default.  That should be addressed
>>> via CSS file in the ovs-sphinx-theme.
>>>
>>> Signed-off-by: Ilya Maximets <i.maximets@ovn.org>
>>> ---
>>
>> Looks like it stopped working about a month ago.  Good future idea for a
>> bot to monitor this part.
>>
>> Anyway:
>>
>> Acked-by: Aaron Conole <aconole@redhat.com>
> 
> Thanks!  Applied.

Backported this to 3.2 as well, because rtd also builds the 'stable'
version from the latest tag.  It will rebuild the docs once the
new tag (v3.2.2) is available.

> 
> And the build passed!
> 
> Best regards, Ilya Maximets.