Re: [documentation] [OpenDaylight TSC] Docs branching


Anil Belur
 

I can add the active ODL doc projects committers to RTD to manage the builds. 
Please create an account and share your ID directly to me on through a ticket.


On Fri, Apr 9, 2021 at 11:57 PM Anil Belur <abelur@...> wrote:
I've triggered the builds for all the projects in the console log and activated branch stable/silicon. However, for a genius and netvirt the issue persists.

13:46:05 /w/workspace/docs-tox-verify-silicon/docs/developer-guides/index.rst:36: WARNING: unknown document: netvirt:index
13:46:05 /w/workspace/docs-tox-verify-silicon/docs/index.rst:60: WARNING: unknown document: genius:index
13:46:05 /w/workspace/docs-tox-verify-silicon/docs/index.rst:61: WARNING: unknown document: netvirt:index
13:46:05 /w/workspace/docs-tox-verify-silicon/docs/user-guide/index.rst:21: WARNING: unknown document: netvirt:index
13:46:05 build succeeded, 6 warnings. 

Netvirt does not seem to have the branch for stable/silicon.


On Fri, Apr 9, 2021 at 9:36 PM Thanh Ha <zxiiro@...> wrote:


On Fri, Apr 9, 2021 at 1:36 AM Anil Belur <abelur@...> wrote:
Hello Thanh, :-)  Thanks for the suggestion. 

I have already activated 'stable/silicon' branch for ODL.
 
To be clear this has to be activated for every project, not just the top level OpenDaylight docs project. Every project that has "WARNING: unknown document:" in the verify job is due to them missing their silicon branches activated in RTD.
 
However, for controller (SM project), I'm unable to find the v3.0.6 branch in the filters. 
Is this because the branch has not been cut yet?

The branch is cut and you can confirm in Git / GitHub by checking what branches or tags are available. RTD doesn't update it's list until a job has run to query the repo. The list may be out of date if the project hasn't had any recently run RTD builds. You can force a build of the project by logging into RTD and clicking build for any of the available branches. Then the v3.0.6 should appear shortly after the build starts.

Regards,
Thanh

Cheers,
Anil

On Fri, Apr 9, 2021 at 12:55 PM Thanh Ha <zxiiro@...> wrote:
When branching a new release someone has to login to ReadTheDocs and activate the new version or branch of the docs for every single project in that list. ReadTheDocs does not automatically generate docs for branches until they are "Activated" in the RTD WebUI.

So for MRI projects like controller the 3.0.6 version must be activated. For autorelease projects like BGPCEP the stable-silicon branch has to be activated. Only then will RTD generate docs pages for those versions.

I believe only the LF has an account with access to every project in ODL via the odl-rtd account so the fastest way to get this done is for LF releng to handle it.

Regards,
Thanh

On Thu, Apr 8, 2021 at 9:31 PM Anil Belur <abelur@...> wrote:
For CR: https://git.opendaylight.org/gerrit/c/docs/+/95685

RTD verify fails because of the following errors: Likely because an object has moved or no longer exists.

11:15:31 failed to reach any of the inventories with the following issues:
11:15:31 intersphinx inventory 'https://docs.opendaylight.org/projects/controller/en/v3.0.6/objects.inv' not fetchable due to <class 'requests.exceptions.HTTPError'>: 404 Client Error: Not Found for url: https://docs.opendaylight.org/projects/controller/en/v3.0.6/objects.inv 
11:15:32 ERROR: InvocationError for command /w/workspace/docs-rtd-verify-silicon/.tox/docs/bin/sphinx-build -j auto -W -b html -n -d /w/workspace/docs-rtd-verify-silicon/.tox/docs/tmp/doctrees ./docs/ /w/workspace/docs-rtd-verify-silicon/docs/_build/html (exited with code 2)

Has anything changed with controller $project docs since this error looks valid? 

As for the docs-verify job goes, its failing because of the following errors:

11:23:28 /w/workspace/docs-tox-verify-silicon/docs/developer-guides/index.rst:34: WARNING: unknown document: infrautils:index
11:23:28 /w/workspace/docs-tox-verify-silicon/docs/developer-guides/index.rst:35: WARNING: unknown document: jsonrpc:index
11:23:28 /w/workspace/docs-tox-verify-silicon/docs/developer-guides/index.rst:36: WARNING: unknown document: netvirt:index
11:23:28 /w/workspace/docs-tox-verify-silicon/docs/developer-guides/index.rst:37: WARNING: unknown document: ovsdb:index
11:23:28 /w/workspace/docs-tox-verify-silicon/docs/developer-guides/index.rst:38: WARNING: unknown document: transportpce:index
11:23:28 /w/workspace/docs-tox-verify-silicon/docs/index.rst:30: WARNING: unknown document: integration-distribution:index
11:23:28 /w/workspace/docs-tox-verify-silicon/docs/index.rst:43: WARNING: unknown document: bgpcep:index
11:23:28 /w/workspace/docs-tox-verify-silicon/docs/index.rst:44: WARNING: unknown document: controller:index
11:23:28 /w/workspace/docs-tox-verify-silicon/docs/index.rst:45: WARNING: unknown document: daexim:index
11:23:28 /w/workspace/docs-tox-verify-silicon/docs/index.rst:46: WARNING: unknown document: infrautils:index
11:23:28 /w/workspace/docs-tox-verify-silicon/docs/index.rst:47: WARNING: unknown document: jsonrpc:index
11:23:28 /w/workspace/docs-tox-verify-silicon/docs/index.rst:48: WARNING: unknown document: lispflowmapping:index
11:23:28 /w/workspace/docs-tox-verify-silicon/docs/index.rst:51: WARNING: unknown document: openflowplugin:index
11:23:28 /w/workspace/docs-tox-verify-silicon/docs/index.rst:52: WARNING: unknown document: ovsdb:index
11:23:28 /w/workspace/docs-tox-verify-silicon/docs/index.rst:60: WARNING: unknown document: genius:index
11:23:28 /w/workspace/docs-tox-verify-silicon/docs/index.rst:61: WARNING: unknown document: netvirt:index
11:23:28 /w/workspace/docs-tox-verify-silicon/docs/index.rst:62: WARNING: unknown document: transportpce:index
11:23:28 /w/workspace/docs-tox-verify-silicon/docs/release-process/managed-release.rst:594: WARNING: undefined label: add-proj-dist (if the link has no caption the label must precede a section header)
11:23:28 /w/workspace/docs-tox-verify-silicon/docs/user-guide/index.rst:20: WARNING: unknown document: jsonrpc:index
11:23:28 /w/workspace/docs-tox-verify-silicon/docs/user-guide/index.rst:21: WARNING: unknown document: netvirt:index
11:23:28 /w/workspace/docs-tox-verify-silicon/docs/user-guide/index.rst:22: WARNING: unknown document: ovsdb:index
11:23:28 build finished with problems, 33 warnings. 


On Fri, Apr 9, 2021 at 11:06 AM Anil Belur <abelur@...> wrote:
Noticed intermittent DNS issues on the RTD, which are resolved on a recheck on master (phosphorous). CR #95686 is ready for review.


On Fri, Apr 9, 2021 at 10:16 AM Anil Belur via lists.opendaylight.org <abelur=linuxfoundation.org@...> wrote:
Luis: I've created new stable/silicon branches on RTD and now ran a "recheck" the CR's. The branching issue is resolved now, while the verify job are still failing on linkcheck failures:

09:59:13 (line    7) broken    https://www.sphinx-doc.org/en/master/ - HTTPSConnectionPool(host='www.sphinx-doc.org', port=443): Max retries exceeded with url: /en/master/ (Caused by NewConnectionError('<urllib3.connection.HTTPSConnection object at 0x7f7387762978>: Failed to establish a new connection: [Errno -2] Name or service not known',))
09:59:13 (line  123) broken    https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html - HTTPSConnectionPool(host='www.sphinx-doc.org', port=443): Max retries exceeded with url: /en/master/usage/restructuredtext/basics.html (Caused by NewConnectionError('<urllib3.connection.HTTPSConnection object at 0x7f73879ada20>: Failed to establish a new connection: [Errno -2] Name or service not known',))
09:59:13 (line  355) broken    https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html - HTTPSConnectionPool(host='www.sphinx-doc.org', port=443): Max retries exceeded with url: /en/master/usage/restructuredtext/basics.html (Caused by NewConnectionError('<urllib3.connection.HTTPSConnection object at 0x7f73879ada20>: Failed to establish a new connection: [Errno -2] Name or service not known',))
09:59:13 (line    7) broken    https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html - HTTPSConnectionPool(host='www.sphinx-doc.org', port=443): Max retries exceeded with url: /en/master/usage/restructuredtext/basics.html (Caused by NewConnectionError('<urllib3.connection.HTTPSConnection object at 0x7f7387762128>: Failed to establish a new connection: [Errno -2] Name or service not known',))
09:59:13 (line  304) broken    https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html - HTTPSConnectionPool(host='www.sphinx-doc.org', port=443): Max retries exceeded with url: /en/master/usage/restructuredtext/roles.html (Caused by NewConnectionError('<urllib3.connection.HTTPSConnection object at 0x7f7387762780>: Failed to establish a new connection: [Errno -2] Name or service not known',))
09:59:13 (line  416) broken    https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html - HTTPSConnectionPool(host='www.sphinx-doc.org', port=443): Max retries exceeded with url: /en/master/usage/restructuredtext/basics.html (Caused by NewConnectionError('<urllib3.connection.HTTPSConnection object at 0x7f7387762128>: Failed to establish a new connection: [Errno -2] Name or service not known',))
09:59:13 (line  416) broken    https://www.sphinx-doc.org/en/master/ - HTTPSConnectionPool(host='www.sphinx-doc.org', port=443): Max retries exceeded with url: /en/master/ (Caused by NewConnectionError('<urllib3.connection.HTTPSConnection object at 0x7f7387762978>: Failed to establish a new connection: [Errno -2] Name or service not known',))

I'll continue to look into this an update here.

On Thu, Apr 8, 2021 at 10:34 AM Luis Gomez <ecelgp@...> wrote:
I followed this: https://git.opendaylight.org/gerrit/gitweb?p=docs.git;a=blob;f=branch-cutting-checklist.txt;h=a1bb775d0b90c9c95a472715b01c6f49d7030eb6;hb=refs/heads/master

I also looked at the RTD script and it seems like some projects are missing there including the docs project itself, so better do the change in RTD directly.

BR/Luis


On Apr 7, 2021, at 3:40 PM, Anil Belur <abelur@...> wrote:

Luis, I'll look into this and get back to you. Did we follow any docs for branching/tagging the docs project?

On Wed, Apr 7, 2021 at 1:23 PM Luis Gomez <ecelgp@...> wrote:
FYI, docs project has branched for silicon release however the "after branching" patches fail:

https://git.opendaylight.org/gerrit/c/docs/+/95685
https://git.opendaylight.org/gerrit/c/docs/+/95686

The reason is we have to activate the new branch (stable-silicon) in RTD but I do not have permission for doing that. Can anyone in LF take care of this? should I open an IT ticket?

BR/Luis










Join TSC@lists.opendaylight.org to automatically receive all group messages.