Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

build: unbreak dependency tracking, doc builds and multiline tables #499

Merged
merged 3 commits into from
Mar 15, 2024
Merged

build: unbreak dependency tracking, doc builds and multiline tables #499

merged 3 commits into from
Mar 15, 2024

Commits on Mar 13, 2024

  1. build: specify dependencies directly in setup.cfg 

    In tox v4, "reuse of environments" was disabled [1]. This is then later
explained [2] to refer to exactly that thing which we were using for
inheriting the dependencies from the top-level testenv all the way to
the docs build. That's why the docs build in GitHub CI started failing.

IMHO, The Correct Way™ of specifying what dependencies are used for
which feature are the so-called "extra dependencies". Once they are in
place, it is be possible to install gnpy via, e.g., `pip install
oopt-gnpy[docs]`. However, this process is (as far as I can tell)
incompatible with `requirements.txt`; all my attempts at using the
standard dependency syntax in that file have failed for me.

So, in order to make this happen, let's move all the dependencies from a
more-or-less ad-hoc collection of files to this declarative approach
right in setup.cfg. That way, the deps are listed on a single place, in
a declarative manner, and as a result, the installation is now a trivial
pip oneliner.

As a result, one can also remove that duplication of dependencies in
docs requirements.

[1] https://tox.wiki/en/4.11.4/upgrading.html#reuse-of-environments
[2] https://tox.wiki/en/4.11.4/upgrading.html#packaging-configuration-and-inheritance

Change-Id: I34aa0c71e993b39e2b805a7de40e133b4d290318
Fixes: 47c8962 fix docs requirements
    @jktjkt
    jktjkt committed Mar 13, 2024
    Configuration menu
    Copy the full SHA
    2d68b94 View commit details
    Browse the repository at this point in the history

  2. docs: try to unbreak the readthedocs.io build 

    It was failing with a message:

  Config validation error in build.os. Value os not found.

Apparently, the v2 config file is mandatory, so let's do that.

Change-Id: I267d5314db026de532b2b6644f500d25de08e343
    @jktjkt
    jktjkt committed Mar 13, 2024
    Configuration menu
    Copy the full SHA
    3a733b1 View commit details
    Browse the repository at this point in the history

  3. docs: use the default theme on ReadTheDocs.org as well 

    Historically, we've been using the RTD theme on the RTD site which hosts
the docs for us, and a Sphinx-default, "Alabaster" theme for other docs
builds. Doing that however started failing:

 Traceback (most recent call last):
   File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/builders/html/__init__.py", line 1096, in handle_page
     output = self.templates.render(templatename, ctx)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/readthedocs_ext/readthedocs.py", line 181, in rtd_render
     content = old_render(template, render_context)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/jinja2glue.py", line 194, in render
     return self.environment.get_template(template).render(context)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/jinja2/environment.py", line 1301, in render
     self.environment.handle_exception()
   File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/jinja2/environment.py", line 936, in handle_exception
     raise rewrite_traceback_stack(source=source)
   File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/themes/basic/page.html", line 10, in top-level template code
     {%- extends "layout.html" %}
     ^^^^^^^^^^^^^^^^^^^^^^^^^
   File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/themes/classic/layout.html", line 10, in top-level template code
     {%- extends "basic/layout.html" %}
     ^^^^^^^^^^^^^^^^^^^^^^^^^
   File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/themes/default/../basic/layout.html", line 170, in top-level template code
     {%- block content %}
   File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/themes/default/../basic/layout.html", line 189, in block 'content'
     {%- block sidebar2 %}{{ sidebar() }}{% endblock %}
     ^^^^^^^^^^^^^^^^^^^^^^^^^
   File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/themes/default/../basic/layout.html", line 189, in block 'sidebar2'
     {%- block sidebar2 %}{{ sidebar() }}{% endblock %}
     ^^^^^^^^^^^^^^^^^^^^^^^^^
   File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/jinja2/sandbox.py", line 393, in call
     return __context.call(__obj, *args, **kwargs)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/jinja2/runtime.py", line 777, in _invoke
     rv = self._func(*arguments)
          ^^^^^^^^^^^^^^^^^^^^^^
   File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/themes/default/../basic/layout.html", line 63, in template
     {%- include sidebartemplate %}
     ^^^^^^^^^^^^^^^^^^^^^^^^^
   File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/jinja2glue.py", line 215, in get_source
     raise TemplateNotFound(template)
 jinja2.exceptions.TemplateNotFound: about.html

 The above exception was the direct cause of the following exception:

 Traceback (most recent call last):
   File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/cmd/build.py", line 281, in build_main
     app.build(args.force_all, args.filenames)
   File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/application.py", line 347, in build
     self.builder.build_update()
   File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 310, in build_update
     self.build(to_build,
   File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 376, in build
     self.write(docnames, list(updated_docnames), method)
   File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 571, in write
     self._write_serial(sorted(docnames))
   File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 581, in _write_serial
     self.write_doc(docname, doctree)
   File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/builders/html/__init__.py", line 672, in write_doc
     self.handle_page(docname, ctx, event_arg=doctree)
   File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/builders/html/__init__.py", line 1103, in handle_page
     raise ThemeError(__("An error happened in rendering the page %s.\nReason: %r") %
 sphinx.errors.ThemeError: An error happened in rendering the page about-project.
 Reason: TemplateNotFound('about.html')

 Theme error:
 An error happened in rendering the page about-project.
 Reason: TemplateNotFound('about.html')

I have no clue what that means because we have never requested this
`about.html`, nor do we reference that file from anywhere. Chances are
that it's "just" some version pinning/compatibility issue, but hey --
why mess with that when there's a perfectly good default theme that
we're using for other purposes already.

As a side effect, this also solves that long-standing issue that Esther
reported where the tables have overly long lines. Apparently, it's a
theme-specific misfeature (readthedocs/sphinx_rtd_theme/Telecominfraproject#117), and the
Alabaster one doesn't suffer from that.

All hail alabaster!

Change-Id: I857890f29f14b7c0f66bca201c9a9c1b1cbf8841
    @jktjkt
    jktjkt committed Mar 13, 2024
    Configuration menu
    Copy the full SHA
    5b6f8c6 View commit details
    Browse the repository at this point in the history