Update docs #2373

aknierim · 2023-07-04T13:43:13Z

Docs are now built with Sphinx 6.2.1 and the PyData theme

* Added PyData theme * Modified front page * Fixed warnings during build of the docs with the Sphinx 6.2.1 * Added version switcher

review-notebook-app · 2023-07-04T13:43:17Z

Check out this pull request on

See visual diffs & provide feedback on Jupyter Notebooks.

Powered by ReviewNB

* Added PyData theme * Modified front page * Fixed warnings during build of the docs with the Sphinx 6.2.1 * Added version switcher

…-docs

* Fixed warnings by changing ``automodapi`` to ``automodule`` at certain locations * Added change log rst file * Removed unused import of ``pydata_sphinx_theme`` * Updated environment.yml

* Added ``:noindex:`` to get rid of warnings * Works at least locally

docs/conf.py

* use autosummary and some manually added titles instead of automodapi in ``ctapipe_api/instrument/camera.rst`` and ``ctapipe_api/calib/index.rst`` * allows to circumvent duplicate reference warnings * removed ``nipick_ignore`` entries added in previous commits of this ``update-docs`` branch

docs/ctapipe_api/calib/index.rst

Not adding to ``__all__`` in ``ctapipe/calib/index_camera/__init__.py`` and ``ctapipe/instrument/camera/__init__.py`` fixes nitpick warnings with automodapi. Note that importing the modules is still necessary.

* Change back to ``automodapi`` in ``ctapipe_api/calib/index.rst`` and ``ctapipe_api/instrument/camera.rst`` * Previous workaround no longer necessary * Fix mobile layout of front page (grid cards now display correctly) * Cleaner docs front page

Ignore unused import warnings in ``ctapipe/calib/camera/__init__.py`` ``ctapipe/instrument/camera/__init__.py`` using ``noqa: F401``. This will allow the linting CI to run successfully, while still allowing the docs to be built with ``automodapi``.

kosack · 2023-07-10T10:19:51Z

For review: here is the RTD link for this PR

maxnoe · 2023-07-17T11:30:21Z

environment.yml

@@ -47,5 +48,5 @@ dependencies:
  - zlib
  - zstandard
  - eventio>=1.9.1
-  - jinja2=3.0 # for sphinx 3.5, remove when updating to 4.x
+  - jinja2


can be completely removed

* Remove version switcher since it needs to be updated by hand every time a new version is released * Remove now-obsolete ``docs/_static/switcher.json`` * Remove ``jinja2`` dependency from ``environment.yml``

aknierim · 2023-07-17T13:00:25Z

Removed the version switcher from the navbar per request by @maxnoe as it has to be updated by hand every time a new version is released.

kosack · 2023-07-17T17:53:10Z

docs/conf.py

+    ],
+}
+
+html_sidebars = {"**": ["sidebar-nav-bs.html", "sidebar-ethical-ads.html"]}


This is a bit of a waste of space: there is no content in the sidebar for most of the pages

The version switcher is there. We had an alternative version, but that would require manually curating a json file of versions.

Yeah, you're right, but this is currently the only way to get the version switcher from RTD. The way I see it, we currently have three options:

We go back and reimplement the dropdown menu I previously added. This however would mean that we have to add any new version to a JSON file by hand.

We use the flyout menu from RTD, thus making it necessary to have the sidebar on all pages.

We use the flyout menu only on specific pages like the front page and for example the API docs.

I'm not sure which option is the best as I guess all of them have their drawbacks...

Hmm, this works fine in the vodf pages I created.. Not sure how I configured it, but there the switcher is floating on the lower-right corner: https://vodf.readthedocs.io/en/latest/ (and also in the top-bar)

Of course the ethical ads don't appear though

I tried to figure out why the behaviour is so different from your vodf pages today but couldn't find anything. My only guess would be different behaviour when using Sphinx 4.5 and PyData 0.10 for the vodf pages versus the ctapipe docs with Sphinx 6.2.1 and PyData 0.13.3...

The version switcher in the navbar on the vodf pages is of course the same one that uses the manually curated json file. But the version switcher from RTD is what boggles my mind.

At least from what I gathered from the PyData theme dev docs and an open issue, they are currently working on a way to make the RTD version switcher more customizable, or at least movable from the sidebar. But for the time being it should actually only appear in the primary sidebar (if not hidden) on the left.

Who knows? I can try updating the VODF docs and see if it disappears... You're right that it's not quite the same version.

But we can deal with that in a later PR, for now it's fine.

* Move content of caution admonition block to announcement banner, as this results in a cleaner main page * Remove ``html_sidebars`` for testing purposes

At least we have a version switcher for now

maxnoe · 2023-07-19T11:51:00Z

Okay, maybe we just bite the bullet and have the manual switcher. Sorry for going back and forth.

It looks much better, doesn't have the sidebar space issue and we already have manual steps in the release process like rendering the changelog.

So let's maybe go for that (and add a section on "how to make a release" to the developer documentation).

I can do that as part of #2383 , after we merge here.

docs/_static/switcher.json

* Stable is now called stable (without version tag) * Add colors to stable and dev versions in switcher

kosack · 2023-07-20T10:58:21Z

The only thing I would suggest is that maybe the top-level admonition about the instability is a bit much: it takes up a lot of page space. Just having it as a disclaimer on the main page is probably fine. Most people understand that a 0.X release is unstable

maxnoe · 2023-07-20T12:07:24Z

The only thing I would suggest is that maybe the top-level admonition about the instability is a bit much: it takes up a lot of page space.

I said the same, but we discussed that most people probably don't enter through the main page. I don't have a strong opinion on this.

Let's merge here so we have an up-to-date sphinx and a better design and do more content changes in other PRs.

aknierim added 4 commits July 4, 2023 15:29

Update environment.yml and setup.cfg to latest version of sphinx

0c13026

Moved docs/_static/theme_overrides.css to docs/_static/ctapipe.css

501f2a9

Added logos dark/light

135df80

Updated docs, added version switcher

11275ed

* Added PyData theme * Modified front page * Fixed warnings during build of the docs with the Sphinx 6.2.1 * Added version switcher

aknierim marked this pull request as draft July 4, 2023 13:43

aknierim added 13 commits July 4, 2023 15:53

Update setup.cfg pydata dependency

c1eef15

Added sphinx-design

a76a43d

Update environment.yml and setup.cfg to latest version of sphinx

c60a81e

Moved docs/_static/theme_overrides.css to docs/_static/ctapipe.css

658fb6a

Added logos dark/light

d2a6d54

Updated docs, added version switcher

b97b531

* Added PyData theme * Modified front page * Fixed warnings during build of the docs with the Sphinx 6.2.1 * Added version switcher

Update setup.cfg pydata dependency

40aab03

Added sphinx-design

bc9d6d7

Merge branch 'update-docs' of github.com:aknierim/ctapipe into update…

1050126

…-docs

Fixed sphinx warning for ctapipe.compat.StrEnum

07ce4ba

Fixed sphinx warnings for ctapipe.instrument

c025fe3

* Fixed warnings by changing ``automodapi`` to ``automodule`` at certain locations * Added change log rst file * Removed unused import of ``pydata_sphinx_theme`` * Updated environment.yml

Attempt at a temporary workaround

2aed4de

Added :noindex: option to certain rst files

8b60b9a

* Added ``:noindex:`` to get rid of warnings * Works at least locally

maxnoe reviewed Jul 5, 2023

View reviewed changes

docs/conf.py Outdated Show resolved Hide resolved

kosack reviewed Jul 7, 2023

View reviewed changes

docs/ctapipe_api/calib/index.rst Outdated Show resolved Hide resolved

aknierim added 5 commits July 7, 2023 10:22

Fix heading issue

958e5d9

Not adding to __all__ fixes automodapi warnings

1618eb1

Not adding to ``__all__`` in ``ctapipe/calib/index_camera/__init__.py`` and ``ctapipe/instrument/camera/__init__.py`` fixes nitpick warnings with automodapi. Note that importing the modules is still necessary.

Ignore unused import warnings

246639f

Ignore unused import warnings in ``ctapipe/calib/camera/__init__.py`` ``ctapipe/instrument/camera/__init__.py`` using ``noqa: F401``. This will allow the linting CI to run successfully, while still allowing the docs to be built with ``automodapi``.

Fix isort failing in ctapipe/instrument/camera/__init__.py

3c0223b

aknierim marked this pull request as ready for review July 10, 2023 10:17

aknierim requested a review from watsonjj as a code owner July 10, 2023 10:17

maxnoe added 5 commits July 17, 2023 11:46

Fix broken html syntax in Component.__repr_html__

c0dc668

Clear notebook outputs

2f16d23

Fix add_css_file call in docs/conf.py

4f5f051

Fix Tool repr_html and add html escaping

63b9e63

Simplify __init__.py

beb5fad

maxnoe reviewed Jul 17, 2023

View reviewed changes

kosack previously approved these changes Jul 17, 2023

View reviewed changes

Remove version switcher from navbar

02798cb

* Remove version switcher since it needs to be updated by hand every time a new version is released * Remove now-obsolete ``docs/_static/switcher.json`` * Remove ``jinja2`` dependency from ``environment.yml``

aknierim dismissed kosack’s stale review via 02798cb July 17, 2023 12:58

aknierim added 2 commits July 17, 2023 15:49

Add sidebar to all pages

a089c49

Fix for failed CI/lint

61547d2

aknierim requested a review from maxnoe July 17, 2023 14:16

kosack reviewed Jul 17, 2023

View reviewed changes

aknierim added 3 commits July 18, 2023 17:52

Move content of caution admonition to announcement banner

22d2062

* Move content of caution admonition block to announcement banner, as this results in a cleaner main page * Remove ``html_sidebars`` for testing purposes

Add sphinx conf path to .readthedocs.yml

2a6b6ed

Add sidebars again

854a84e

At least we have a version switcher for now

Add navbar version switcher

c782ba0

maxnoe reviewed Jul 19, 2023

View reviewed changes

docs/_static/switcher.json Outdated Show resolved Hide resolved

Fix versions in switcher.json

05cc382

* Stable is now called stable (without version tag) * Add colors to stable and dev versions in switcher

kosack approved these changes Jul 20, 2023

View reviewed changes

maxnoe approved these changes Jul 20, 2023

View reviewed changes

maxnoe merged commit c7f5ee2 into cta-observatory:main Jul 20, 2023
12 of 13 checks passed

aknierim deleted the update-docs branch July 20, 2023 12:08

maxnoe mentioned this pull request Jul 21, 2023

Update doc structure and dev guide #2383

Merged

kosack added the documentation label Sep 7, 2023

maxnoe mentioned this pull request Oct 21, 2023

Switch to PyData Sphinx theme #1826

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update docs #2373

Update docs #2373

aknierim commented Jul 4, 2023 •

edited

review-notebook-app bot commented Jul 4, 2023

kosack commented Jul 10, 2023

maxnoe Jul 17, 2023

aknierim commented Jul 17, 2023

kosack Jul 17, 2023

maxnoe Jul 17, 2023

aknierim Jul 17, 2023

kosack Jul 18, 2023 •

edited

kosack Jul 18, 2023

aknierim Jul 18, 2023 •

edited

aknierim Jul 18, 2023 •

edited

kosack Jul 19, 2023

kosack Jul 19, 2023

maxnoe commented Jul 19, 2023

kosack commented Jul 20, 2023

maxnoe commented Jul 20, 2023

Update docs #2373

Update docs #2373

Conversation

aknierim commented Jul 4, 2023 • edited

review-notebook-app bot commented Jul 4, 2023

kosack commented Jul 10, 2023

maxnoe Jul 17, 2023

Choose a reason for hiding this comment

aknierim commented Jul 17, 2023

kosack Jul 17, 2023

Choose a reason for hiding this comment

maxnoe Jul 17, 2023

Choose a reason for hiding this comment

aknierim Jul 17, 2023

Choose a reason for hiding this comment

kosack Jul 18, 2023 • edited

Choose a reason for hiding this comment

kosack Jul 18, 2023

Choose a reason for hiding this comment

aknierim Jul 18, 2023 • edited

Choose a reason for hiding this comment

aknierim Jul 18, 2023 • edited

Choose a reason for hiding this comment

kosack Jul 19, 2023

Choose a reason for hiding this comment

kosack Jul 19, 2023

Choose a reason for hiding this comment

maxnoe commented Jul 19, 2023

kosack commented Jul 20, 2023

maxnoe commented Jul 20, 2023

aknierim commented Jul 4, 2023 •

edited

kosack Jul 18, 2023 •

edited

aknierim Jul 18, 2023 •

edited

aknierim Jul 18, 2023 •

edited