search

brightway-lca / brightway-documentation

📚🌿 readthedocs.org Sphinx Documentation for Brightway
https://docs.brightway.dev
BSD 3-Clause "New" or "Revised" License
10 stars 45 forks source link

Resolve Brightway Package Docstring Cross-Referencing Issues #112

Open michaelweinold opened 1 year ago

michaelweinold commented 1 year ago

During investigation of https://github.com/brightway-lca/brightway-documentation/issues/111 I found that Sphinx currently throws a number of warnings related to the use of the :ref: role in the Python function docstrings. Some examples:

api/bw2data/backends/single_file/proxies/index.rst:73: WARNING: undefined label: 'activity'
api/bw2data/data_store/index.rst:27: WARNING: undefined label: 'serialized-dict'
api/bw2data/data_store/index.rst:134: WARNING: undefined label: 'mapping'
api/bw2data/data_store/index.rst:134: WARNING: undefined label: 'geomapping'
api/bw2data/data_store/index.rst:140: WARNING: undefined label: 'processing-data'

I investigated two cases:

  1. geomapping

The :ref: that throws the error is used in

class ProcessedDataStore in bw2data/data_store.py:

This method takes the entire dataset, and loads objects to :ref:`mapping` or :ref:`geomapping` as needed.

aliased at

bw2data/meta.py:

geomapping = GeoMapping()

and originally defined as class GeoMapping() in bw2data/meta.py.

In this case: We should investigate if/how Sphinx can work with aliases of this nature (this is actually related to the larger discussion here: https://github.com/brightway-lca/brightway-documentation/discussions/83#discussioncomment-5914938).

  1. serialized-dict

The :ref: that throws the error is used in

class DataStore in bw2data/data_store.py:

* **metadata**: A :ref:`serialized-dict` instance, e.g. ``databases`` or ``methods``.

and originally defined as class SerializedDict() in bw2data/serialization.py.

In this case: Since serialized-dict is used only once in bw2data and only in a docstring, it seems that it was never aliased to SerializedDict.

We should clear this up because:

  1. I didn't find a way to suppress the Sphinx warnings related to broken :ref: use.
  2. I don't want to find a way to suppress the Sphinx warnings related to broken :ref: use, since this would likely disallow for the planned use of the linkcheck builder: https://github.com/brightway-lca/brightway-documentation/issues/95
  3. The number of bad uses of :ref: is limited in scope.
michaelweinold commented 1 year ago

...@cmutel, this could be a job for @Cerebrovinny later this year - let's discuss this at/around Brightcon.