and of the class referenced in the documentation
example-data folder is not accessible from the
generated pages on readthedocs. So use hyperlinks
to the files github repo.
Signed-off-by: EstherLerouzic <esther.lerouzic@orange.com>
Change-Id: I135e2cb0b0d28fecffcbcbfec9a9d6c8cb5c7347
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/#117), and the
Alabaster one doesn't suffer from that.
All hail alabaster!
Change-Id: I857890f29f14b7c0f66bca201c9a9c1b1cbf8841
Python 3.10 builds require a fix in Sphinx, so let's update all docs
dependencies while we're at this.
Unfortunately, the myst-parser requires docutils<0.18,>=0.15 so we
cannot take the latest and greatest of that one.
After this update, sphinxcontrib-bibtex now requires an explicit
reference to the .bib files directly in the config file. Let's remove
the one in the actual docs, then.
Bug: https://github.com/sphinx-doc/sphinx/pull/9513
Change-Id: I80f62131b25f3afa23351646001f6ce381723487
In the past, we had some manual version info in this file, but
apparently it never got updated past the 0.1 release (yay). The, in
4d5d10935 I changed this to retrieve the version information via PBR's
existing magic. That worked well, showing the abbreviated commit hash at
the footer on ReadTheDocs, but I don't think it was terribly useful:
- it was just a hash, nothing like the output of `git describe` (i.e.,
no tag info was there),
- it wasn't showing up in local docs builds which use the Alabaster
default theme.
Now, in 1b2eb9a5 I split the dependency handling. The idea was to make
sure that a "regular installation" would not pull the docs in
needlessly. Unfortunately, the way I set up the RTD builds, the common
dependencies were skipped, and as a result, the `pbr` package was not
available to RTD, and stuff failed.
I could have configured RTD to *also* install from the main deps, but I
don't think this is actually needed. Given that the version info is
rather subtle, let's skip it altogether. Instead, it's better to use
RTD's built-in features for switching between docs for a particular
release (via a git tag) and for the generic "master branch".
Change-Id: Iab0cc9608fa6c24eba93d772370ecd379cf65b1e
Fixes: 1b2eb9a5 (docs: separate out dependencies)
Image source: I took the existing banner, cropped it and resized to
200px width as per the theme docs.
Change-Id: Ic79b6164d557298746fe878de31ee0a9b0d93923
It turns out that our current setup does not really support the `sdist`
Python packaging step. I'm trying to increase automation, both for
making releases for upload to pypi.org, and also for CI via Zuul. As it
turns out, Zuul comes with a set of predefined jobs which -- by default
-- use `tox`, and tox was having troubles dealing with our `setup.py`
because it also assumes that the `sdist` step works. It is also supposed
to:
- fix version number duplication in `setup.py`,
- fix version number duplication in Sphinx docs,
- prevent the need to write a `MANIFEST.in` manually.
TL;DR: insetad of having to deal with a ton of other creative
boilerplate, use tools for lazy people like me, and PBR ("Python Build
Reasonableness") appears to check the marks here.
Change-Id: I27c36c4f6b0e76857d16f7819ec237e9b811476a
* Add Travis-CI configuration for continous integration
* Add GN-Model Documentation and auto-doc integration
* Add GN model to Fiber
* Unit of measure conversion adapted to SI
