asdf-format / sphinx-asdf Goto Github PK

View Code? Open in Web Editor NEW

2.0 2.0 9.0 246 KB

Plugin for sphinx for generating documentation from ASDF schemas

License: BSD 3-Clause "New" or "Revised" License

Python 100.00%

sphinx-asdf's People

Contributors

Stargazers

Watchers

Forkers

drdavella astrofrog saimn cagtayfabry eslavich kmacdonald-stsci nden williamjamieson braingram

sphinx-asdf's Issues

Possible typo in `directives.py`

sphinx-asdf/sphinx_asdf/directives.py

Lines 210 to 213 in d81d949

 elif shorten: 

 rename = schema_id 

 return refname, schema_id + fragment

the use of rename was likely meant to be refname. Switching this to refname resulted in asdf and romancal docs build failures so further investigation will be needed.

Formatting bug when rendering raw ASDF

When an ASDF file's content is injected into documentation like this:

.. asdf:: test.asdf

The resulting rendered HTML looks like this:

test.asdfb'#ASDF' 1.5.0
%YAML 1.1
%TAG ! tag:stsci.edu:asdf/
# etc

Something is going on in that first line, the single quotes aren't actually part of the content and the filename shouldn't be run-on with the ASDF header.

Parsing all files add a huge overhead

To find the asdf directive it seems that this plugin relies on fully parsing all the rst files, which on astropy introduces a huge overhead:

find_autoasdf_directives /home/simon/Dev/astro/astropy/docs/api/astropy.wcs.wcsapi.BaseHighLevelWCS.rst : 0.19 sec.
find_autoasdf_directives /home/simon/Dev/astro/astropy/docs/api/astropy.tests.helper.check_pickling_recovery.rst : 0.03 sec.
find_autoasdf_directives /home/simon/Dev/astro/astropy/docs/units/standard_units.rst : 0.08 sec.
find_autoasdf_directives /home/simon/Dev/astro/astropy/docs/api/astropy.utils.misc.JsonCustomEncoder.rst : 0.08 sec.
find_autoasdf_directives /home/simon/Dev/astro/astropy/docs/api/astropy.nddata.PartialOverlapError.rst : 0.03 sec.
find_autoschema_references : 217.85 sec.

I don't know much about Sphinx plugins API but I'm surprised that there is no better way to proceed ?

For reference the code involved here:
https://github.com/spacetelescope/sphinx-asdf/blob/64ed11ab19a007bd1861c82cc2710f1e6ec61286/sphinx_asdf/connections.py#L19-L48

Fix Python 3.7 Travis jobs

Something seems to have changed on Travis since the tests were last run, some jobs are failing due to missing Python 3.7:

https://travis-ci.com/github/asdf-format/sphinx-asdf/jobs/381208483

`rename` or `refname`

As found in #80

sphinx-asdf/sphinx_asdf/directives.py

Lines 210 to 217 in 97f22f6

 elif shorten: 

 # TODO this should probably be: 

 # refname = schema_id 

 # as it was previously 

 # rename = schema_id 

 # and ruff cleaned this up as unused. However, changing it 

 # to refname breaks some downstream packages 

 pass

Determine if this should be refname and why it breaks downstream packages.

Build Error on Python 3.11

When I make the asdf-astropy docs locally in a Python 3.11 virtual env I consistently get the following error:

Extension error (sphinx_asdf.connections):
Handler <function autogenerate_schema_docs at 0x131564f40> for event 'builder-inited' threw an exception (exception: global flags not at the start of the expression at position 441)

I can reproduce this consistently (across newly created clean envs).

pip list:

Package                       Version              Editable project location
----------------------------- -------------------- -----------------------------------------------------
alabaster                     0.7.13
asdf                          2.15.0
asdf-astropy                  0.4.1.dev25+gc6608be /Users/wjamieson/workspaces/asdf-astropy/asdf-astropy
asdf-coordinates-schemas      0.2.0
asdf-standard                 1.0.3
asdf-transform-schemas        0.3.0
asdf-unit-schemas             0.1.0
astropy                       5.3.1
astropy-sphinx-theme          1.1
attrs                         23.1.0
Babel                         2.12.1
certifi                       2023.5.7
charset-normalizer            3.2.0
contourpy                     1.1.0
coverage                      7.2.7
cycler                        0.11.0
docutils                      0.18.1
fonttools                     4.41.0
graphviz                      0.20.1
hypothesis                    6.81.1
idna                          3.4
imagesize                     1.4.1
importlib-metadata            6.8.0
iniconfig                     2.0.0
Jinja2                        3.1.2
jmespath                      1.0.1
jsonschema                    4.17.3
kiwisolver                    1.4.4
MarkupSafe                    2.1.3
matplotlib                    3.7.2
mistune                       3.0.1
numpy                         1.25.1
numpydoc                      1.5.0
packaging                     23.1
Pillow                        10.0.0
pip                           23.1.2
pluggy                        1.2.0
psutil                        5.9.5
pyerfa                        2.0.0.3
Pygments                      2.15.1
pyparsing                     3.0.9
pyrsistent                    0.19.3
pytest                        7.4.0
pytest-arraydiff              0.5.0
pytest-astropy                0.10.0
pytest-astropy-header         0.2.2
pytest-cov                    4.1.0
pytest-doctestplus            0.13.0
pytest-filter-subpackage      0.1.2
pytest-mock                   3.11.1
pytest-openfiles              0.5.0
pytest-remotedata             0.4.0
python-dateutil               2.8.2
PyYAML                        6.0
requests                      2.31.0
scipy                         1.11.1
semantic-version              2.10.0
setuptools                    65.5.0
six                           1.16.0
snowballstemmer               2.2.0
sortedcontainers              2.4.0
Sphinx                        6.2.1
sphinx-asdf                   0.2.0
sphinx-astropy                1.9.1
sphinx-automodapi             0.15.0
sphinx-bootstrap-theme        0.8.1
sphinx-gallery                0.13.0
sphinx-rtd-theme              1.2.2
sphinxcontrib-applehelp       1.0.4
sphinxcontrib-devhelp         1.0.2
sphinxcontrib-htmlhelp        2.0.1
sphinxcontrib-jquery          4.1
sphinxcontrib-jsmath          1.0.1
sphinxcontrib-qthelp          1.0.3
sphinxcontrib-serializinghtml 1.1.5
toml                          0.10.2
tomli                         2.0.1
urllib3                       2.0.3
zipp                          3.16.1

multiline warnings containing links are difficult to click due to resizing

The active resizing to allow for easier reading of asdf file contents limits interaction with links in warning block text.

sphinx-asdf/sphinx_asdf/static/custom.css

Line 7 in da575fb

div.admonition:active {

Perhaps a hover would allow for both uses but would require testing.

CI builds documentation of development packages with released versions

Taking asdf as an example.

sphinx-asdf/tox.ini

Lines 26 to 28 in 6b69e5f

 git clone https://github.com/asdf-format/asdf 

 pip install asdf[docs] 

 sphinx-build asdf/docs asdf/docs/build

results in the CI (based on current versions) installing asdf 2.15 and failing to build documentation for 3.0:
https://github.com/asdf-format/sphinx-asdf/actions/runs/4926082430/jobs/8801158491#step:5:24

Preserve sphinx theme set in project configuration

Currently the generated schema documentation does not conform to the theme that is set in the project's docs/conf.py. This is because we use the sphinx bootstrap stylesheets to generate schema documentation, so they get pulled in regardless of whether the project is using sphinx-bootstrap-theme or not.

I'm not sure whether this will be possible and/or how much effort it is worth.

Tag wildcards do not generate valid schema links

The presence of a wildcard * in a tag directive in a schema makes sphinx-asdf skip link generation:

sphinx-asdf/sphinx_asdf/directives.py

Lines 391 to 392 in 232fd23

 if "*" in _tag: 

 ref = None

It might be possible to resolve the tag version (to the latest tag) prior to generating the link to allow links to be generated for wildcarded tags.

xref: spacetelescope/rad#379

`RemovedInSphinx70Warning: sphinx.io.read_doc() is deprecated.`

It looks like there are a few deprecation errors in RTD builds on Python 3.11:
https://readthedocs.org/projects/jwst-pipeline/builds/20117878/

/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/envs/7552/lib/python3.11/site-packages/sphinx_asdf/connections.py:25: RemovedInSphinx70Warning: sphinx.io.read_doc() is deprecated.
  doctree = read_doc(env.app, env, env.doc2path(docname))

sphinx-asdf/sphinx_asdf/connections.py

Line 25 in 30c62b9

doctree = read_doc(env.app, env, env.doc2path(docname))

It looks like read_doc() was deprecated in Sphinx 5.0.0 b1:
https://www.sphinx-doc.org/en/master/changes.html#id170

use of soon to be non-public api

this plugin reaches into internal asdf structures to allow formatting asdf file contents.
https://github.com/asdf-format/sphinx-asdf/blob/master/sphinx_asdf/asdf2rst.py#L94
Portions of this API have been deprecated asdf-format/asdf#1336 and may require updates to sphinx_asdf

Warning, treated as error:
the sphinx_asdf extension does not declare if it is safe for parallel reading, assuming it isn't - please ask the extension author to check and make it explicit

This seems to be the relevant part regarding extensions in the sphinx documentation:
https://www.sphinx-doc.org/en/master/extdev/index.html#extension-metadata

Any idea if sphinx-asdf is safe for parallel reading and where to add the metadata?

	elif shorten:
	rename = schema_id

	return refname, schema_id + fragment

	elif shorten:
	# TODO this should probably be:
	# refname = schema_id
	# as it was previously
	# rename = schema_id
	# and ruff cleaned this up as unused. However, changing it
	# to refname breaks some downstream packages
	pass

	git clone https://github.com/asdf-format/asdf
	pip install asdf[docs]
	sphinx-build asdf/docs asdf/docs/build

asdf-format / sphinx-asdf Goto Github PK

sphinx-asdf's People

Contributors

Stargazers

Watchers

Forkers

sphinx-asdf's Issues

Recommend Projects

Recommend Topics

Recommend Org