Documentation/remove concepts #591

f-brinkmann · 2024-04-20T11:13:48Z

Which issue(s) are closed by this pull request?

closes #551, part of pyfar/gallery#20

Changes proposed in this pull request:

Move information from Concepts>Coordinates to Classes>Coordinates and update references
Remove all other concepts pages and link to pyfar gallery instead
replace links to gallery with intersphinx links
add introductory section to pyfar.utils linking to cshape, caxis, and cdim

ahms5

Thank you! I just had a look on coordiantes for now.

ahms5 · 2024-04-22T07:24:33Z

pyfar/classes/coordinates.py

-Available sampling schemes are listed at
-:py:mod:`spharpy.samplings <spharpy.samplings>`.
+r"""
+The following introduces the the


Suggested change

The following introduces the the

The following introduces the

pyfar/classes/coordinates.py

ahms5 · 2024-04-22T07:29:11Z

pyfar/classes/coordinates.py

+The unit for length for the coordinates is always meter, while the unit for
+angles is radians. Each coordinate is unique, but can appear in multiple
+coordinate systems, e.g., the `azimuth` angle is contained in two coordinate
+systems (`spherical_colatitude` and `spherical elevation`). The table below


Suggested change

systems (`spherical_colatitude` and `spherical elevation`). The table below

systems (`spherical_colatitude` and `spherical_elevation`). The table below

maybe remove the table (see below) and refer to the example notebook after telling about the coodinates.

Thanks, I fixed the typo. I personally like having the table for a quick overview here.

sikersten

Thanks for taking care! Only minor comments, otherwise approved :)

sikersten · 2024-04-22T08:19:25Z

pyfar/classes/audio.py

-:py:mod:`audio classes <pyfar._concepts.audio_classes>`,
-:py:mod:`Fourier transform <pyfar._concepts.fft>`,
-:py:mod:`arithmetic operations <pyfar._concepts.arithmetic_operations>`).
+audio data. More details and background is given in the gallery (


Maybe just a link to the gallery is sufficient?

Since there are already lots of examples and more will come - so I think explicitly referencing whats important might help new users.

pyfar/classes/coordinates.py

sikersten · 2024-04-22T08:26:11Z

pyfar/samplings/__init__.py

+    This module will be deprecated in pyfar v0.8.0 in favor of
+    :py:mod:`spharpy.samplings <spharpy.samplings>`.


Is this intended to be part of this PR?

It might be a beer. When checking the documentation I thought something like this would be nice to have

f-brinkmann

Thanks for review, commented everywhere :)

f-brinkmann · 2024-04-22T08:46:05Z

pyfar/classes/audio.py

-:py:mod:`audio classes <pyfar._concepts.audio_classes>`,
-:py:mod:`Fourier transform <pyfar._concepts.fft>`,
-:py:mod:`arithmetic operations <pyfar._concepts.arithmetic_operations>`).
+audio data. More details and background is given in the gallery (


Since there are already lots of examples and more will come - so I think explicitly referencing whats important might help new users.

f-brinkmann · 2024-04-22T08:46:37Z

pyfar/classes/coordinates.py

-Available sampling schemes are listed at
-:py:mod:`spharpy.samplings <spharpy.samplings>`.
+r"""
+The following introduces the the


f-brinkmann · 2024-04-22T08:48:15Z

pyfar/samplings/__init__.py

+    This module will be deprecated in pyfar v0.8.0 in favor of
+    :py:mod:`spharpy.samplings <spharpy.samplings>`.


It might be a beer. When checking the documentation I thought something like this would be nice to have

f-brinkmann · 2024-04-22T08:50:43Z

pyfar/classes/coordinates.py

+The unit for length for the coordinates is always meter, while the unit for
+angles is radians. Each coordinate is unique, but can appear in multiple
+coordinate systems, e.g., the `azimuth` angle is contained in two coordinate
+systems (`spherical_colatitude` and `spherical elevation`). The table below


Thanks, I fixed the typo. I personally like having the table for a quick overview here.

pyfar/classes/coordinates.py

ahms5

Thank you, looks like many comments but its just because of using intersphinx instead of direct links to the gallery

ahms5 · 2024-04-26T15:37:28Z

docs/modules/pyfar.dsp.filter.rst

+The following documents the pyfar filters. Visit the
+`filter types <https://pyfar-gallery.readthedocs.io/en/latest/gallery/
+interactive/pyfar_filter_types.html>`_ for an overview of
+the different filters and the
+`filtering examples <https://pyfar-gallery.readthedocs.io/en/latest/
+gallery/interactive/pyfar_filtering.html>`_ for more information
+on using pyfar filter objects.


Suggested change

The following documents the pyfar filters. Visit the

`filter types <https://pyfar-gallery.readthedocs.io/en/latest/gallery/

interactive/pyfar_filter_types.html>`_ for an overview of

the different filters and the

`filtering examples <https://pyfar-gallery.readthedocs.io/en/latest/

gallery/interactive/pyfar_filtering.html>`_ for more information

on using pyfar filter objects.

The following documents the pyfar filters. Visit the

:doc:`gallery:gallery/interactive/fast_fourier_transform` for an overview of

the different filters and the :doc:`gallery:gallery/interactive/pyfar_filtering`

for more information

on using pyfar filter objects.

we need to add

'gallery': ('https://pyfar-gallery.readthedocs.io/en/latest/', None),

to the config.py in intersphinx_mapping then we can use intersphinx to generate the links

ahms5 · 2024-04-26T15:39:30Z

pyfar/classes/audio.py

+`audio objects <https://pyfar-gallery.readthedocs.io/en/latest/gallery/
+interactive/pyfar_audio_objects.html>`_,
+`Fourier transform <https://pyfar-gallery.readthedocs.io/en/latest/gallery/
+interactive/fast_fourier_transform.html>`_,
+`arithmetic operations <https://pyfar-gallery.readthedocs.io/en/latest/gallery/
+interactive/pyfar_arithmetics.html>`__).


Suggested change

`audio objects <https://pyfar-gallery.readthedocs.io/en/latest/gallery/

interactive/pyfar_audio_objects.html>`_,

`Fourier transform <https://pyfar-gallery.readthedocs.io/en/latest/gallery/

interactive/fast_fourier_transform.html>`_,

`arithmetic operations <https://pyfar-gallery.readthedocs.io/en/latest/gallery/

interactive/pyfar_arithmetics.html>`__).

:doc:`gallery:gallery/interactive/pyfar_audio_objects`, :doc:`gallery:gallery/interactive/fast_fourier_transform`, :doc:`gallery:gallery/interactive/pyfar_arithmetics`).

see above to make it work

ahms5 · 2024-04-26T15:40:12Z

pyfar/classes/audio.py

+        `pyfar gallery <https://pyfar-gallery.readthedocs.io/en/latest/gallery/
+        interactive/fast_fourier_transform.html#FFT-normalizations>`_


Suggested change

`pyfar gallery <https://pyfar-gallery.readthedocs.io/en/latest/gallery/

interactive/fast_fourier_transform.html#FFT-normalizations>`_

:doc:`gallery:gallery/interactive/fast_fourier_transform.html#FFT-normalizations`

ahms5 · 2024-04-26T15:40:20Z

pyfar/classes/audio.py

@@ -884,7 +889,9 @@ def add(data: tuple, domain='freq'):
        scalars. Pyfar audio objects can not be mixed, e.g.,
        :py:func:`TimeData` and :py:func:`FrequencyData` objects do not work
        together. See below or
-        :py:mod:`arithmetic operations <pyfar._concepts.arithmetic_operations>`
+        `arithmetic operations <https://pyfar-gallery.readthedocs.io/en/latest/


ahms5 · 2024-04-26T15:40:28Z

pyfar/classes/audio.py

@@ -929,7 +936,9 @@ def subtract(data: tuple, domain='freq'):
        and scalars. Pyfar audio objects can not be mixed, e.g.,
        :py:func:`TimeData` and :py:func:`FrequencyData` objects do not work
        together. See below or
-        :py:mod:`arithmetic operations <pyfar._concepts.arithmetic_operations>`
+        `arithmetic operations <https://pyfar-gallery.readthedocs.io/en/latest/


ahms5 · 2024-04-26T15:43:26Z

pyfar/utils.py

@@ -36,7 +38,9 @@ def broadcast_cshapes(signals, cshape=None):
    """
    Broadcast multiple signals to a common cshape.

-    The :py:mod:`cshape <pyfar._concepts.audio_classes>` of the signals are
+    The `cshape <https://pyfar-gallery.readthedocs.io/en/latest/gallery/


ahms5 · 2024-04-26T15:43:31Z

pyfar/utils.py

@@ -69,7 +73,9 @@ def broadcast_cdim(signal, cdim):
    Broadcast a signal to a certain cdim.

    The channel dimension (cdim) is the length of the
-    :py:mod:`cshape <pyfar._concepts.audio_classes>` of the signal. The signal
+    `cshape <https://pyfar-gallery.readthedocs.io/en/latest/gallery/


ahms5 · 2024-04-26T15:43:34Z

pyfar/utils.py

@@ -103,7 +109,9 @@ def broadcast_cdims(signals, cdim=None):
    Broadcast multiple signals to a common cdim.

    The channel dimension (cdim) is the length of the
-    :py:mod:`cshape <pyfar._concepts.audio_classes>` of the signal. The signals
+    `cshape <https://pyfar-gallery.readthedocs.io/en/latest/gallery/


ahms5 · 2024-04-26T15:43:38Z

pyfar/utils.py

-        background about caxis is given in the concepts of
-        :py:mod:`Audio classes <pyfar._concepts.audio_classes>`.
-        The default is ``0``.
+        The `caxis <https://pyfar-gallery.readthedocs.io/en/latest/gallery/


ahms5 · 2024-04-26T15:43:42Z

pyfar/utils.py

    broadcasting: bool
        If this is ``True``, the signals will be broadcasted to common
        cshape, except for the caxis along which the signals are
        concatenated.
-        The :py:mod:`cshape <pyfar._concepts.audio_classes>` of the signals are
+        The `cshape <https://pyfar-gallery.readthedocs.io/en/latest/gallery/


f-brinkmann · 2024-04-26T16:10:32Z

@ahms5 I did not find a way to link to specific sections using intersphinx, e.g., arithmetic operations <https://pyfar-gallery.readthedocs.io/en/latest/gallery/interactive/pyfar_arithmetics.html#DFT-normalization-and-arithmetic-operations>_ does not work with :doc: gallery:... in addition it seems as if links can't stretch multiple lines, which would force me to ignore a certain PEP to pass flake8/ruff. Not sure if we should leave it as it is...

ahms5 · 2024-04-29T08:05:44Z

@ahms5 I did not find a way to link to specific sections using intersphinx, e.g., arithmetic operations <https://pyfar-gallery.readthedocs.io/en/latest/gallery/interactive/pyfar_arithmetics.html#DFT-normalization-and-arithmetic-operations>_ does not work with :doc: gallery:... in addition it seems as if links can't stretch multiple lines, which would force me to ignore a certain PEP to pass flake8/ruff. Not sure if we should leave it as it is...

I think flake8 is not marking about this, since its not code but a docstring. I also found a way to refer to subsections:

        :ref:`gallery:/gallery/interactive/fast_fourier_transform.ipynb#fft-normalizations`

we need to add this to the doc setup file:

# Add the extension
extensions = [
    "sphinx.ext.autosectionlabel",
]

# Make sure the target is unique
autosectionlabel_prefix_document = True

https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html#automatically-label-sections
If you want me to include it, please let me know.

f-brinkmann · 2024-04-29T10:08:01Z

Not sure if I understand this correctly. Wouldn't we have to add this to gallery to generate the labels? It is also raising a new warning for a duplicate label, so maybe autosectionlabel_prefix_document = True is not working as intended in this case. Go ahead if you want to give it a try.

ahms5 · 2024-04-29T15:48:32Z

yes seems like you even dont need to change the config. You are right, the links are very long some times. Maybe someone has an idea, I'll try to find a solution. Its mostly for the link to the :ref:`arithmetic operations<gallery:/gallery/interactive/fast_fourier_transform.ipynb#FFT-normalizations>` and :ref:`arithmetic operations<gallery:/gallery/interactive/pyfar_arithmetics.ipynb#DFT-normalization-and-arithmetic-operations>` and :ref:`caxis<gallery:/gallery/interactive/pyfar_audio_objects.ipynb#Signal-cshape,-length,-and-caxis>` maybe we can add shortcut in gallery for this links, since we need them quite often

f-brinkmann · 2024-05-03T11:35:20Z

We decided to try to avoid the explicit links in the docstrings of parameters to notebooks section containing information about cshape cdim and caxis, arithmetic operations, etc.

If required they can be moved to the top-level descirotion of the module, function, or class.

f-brinkmann added 7 commits April 20, 2024 11:40

move information from concepts to coordinates class

35c4edc

remove audio concepts and link to gallery instead

dc73012

remove arithmetics concepts and link to gallery instead

8e658bd

remove fft concepts and link to gallery instead

138c0c4

remove filter examples and link to gallery instead

57e4004

remove filter type examples and link to gallery instead

0498351

remove plotting examples and link to gallery instead

a253798

f-brinkmann added the documentation Everything related to docstrings and comments label Apr 20, 2024

f-brinkmann self-assigned this Apr 20, 2024

f-brinkmann mentioned this pull request Apr 20, 2024

Harmonize documentation between pyfar packages pyfar/gallery#20

Open

13 tasks

f-brinkmann added the 0.6.6 label Apr 20, 2024

f-brinkmann requested review from mberz, tluebeck, pingelit, ahms5 and sikersten April 20, 2024 11:45

ahms5 requested changes Apr 22, 2024

View reviewed changes

sikersten reviewed Apr 22, 2024

View reviewed changes

fix typos discovered in review

e6e59a8

f-brinkmann commented Apr 22, 2024

View reviewed changes

f-brinkmann requested review from sikersten and ahms5 April 22, 2024 08:57

f-brinkmann added 4 commits April 26, 2024 16:44

Merge branch 'main' into documentation/remove_concepts

0b6da5d

fix merge conflicts

128ca42

fix broken links in coordinates table

9f3871e

fix confusion with coordinate names and ranges

04bfd4f

f-brinkmann force-pushed the documentation/remove_concepts branch from c6917c4 to 04bfd4f Compare April 26, 2024 15:32

f-brinkmann mentioned this pull request Apr 26, 2024

Fix math and description of coordinates #597

Merged

ahms5 requested changes Apr 26, 2024

View reviewed changes

replace gallery inks by intersphinx definitions

e880f35

ahms5 and others added 2 commits April 29, 2024 17:54

fix flake8

8945651

update according to mberz

4a3bd2c

remove links to notebook section explaining cshape, caxis, and cdim

946af37

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation/remove concepts #591

Documentation/remove concepts #591

f-brinkmann commented Apr 20, 2024 •

edited

ahms5 left a comment

ahms5 Apr 22, 2024

f-brinkmann Apr 22, 2024

ahms5 Apr 22, 2024

f-brinkmann Apr 22, 2024

sikersten left a comment

sikersten Apr 22, 2024

f-brinkmann Apr 22, 2024

sikersten Apr 22, 2024

f-brinkmann Apr 22, 2024

f-brinkmann left a comment

f-brinkmann Apr 22, 2024

f-brinkmann Apr 22, 2024

f-brinkmann Apr 22, 2024

f-brinkmann Apr 22, 2024

ahms5 left a comment

ahms5 Apr 26, 2024

ahms5 Apr 26, 2024

ahms5 Apr 26, 2024

ahms5 Apr 26, 2024

ahms5 Apr 26, 2024

ahms5 Apr 26, 2024

ahms5 Apr 26, 2024

ahms5 Apr 26, 2024

ahms5 Apr 26, 2024

ahms5 Apr 26, 2024

f-brinkmann commented Apr 26, 2024

ahms5 commented Apr 29, 2024

f-brinkmann commented Apr 29, 2024

ahms5 commented Apr 29, 2024

f-brinkmann commented May 3, 2024

	The following introduces the the
	The following introduces the

	systems (`spherical_colatitude` and `spherical elevation`). The table below
	systems (`spherical_colatitude` and `spherical_elevation`). The table below

		This module will be deprecated in pyfar v0.8.0 in favor of
		:py:mod:`spharpy.samplings <spharpy.samplings>`.

		`pyfar gallery <https://pyfar-gallery.readthedocs.io/en/latest/gallery/
		interactive/fast_fourier_transform.html#FFT-normalizations>`_

	`pyfar gallery <https://pyfar-gallery.readthedocs.io/en/latest/gallery/
	interactive/fast_fourier_transform.html#FFT-normalizations>`_
	:doc:`gallery:gallery/interactive/fast_fourier_transform.html#FFT-normalizations`

Documentation/remove concepts #591

Are you sure you want to change the base?

Documentation/remove concepts #591

Conversation

f-brinkmann commented Apr 20, 2024 • edited

Which issue(s) are closed by this pull request?

Changes proposed in this pull request:

ahms5 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sikersten left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

f-brinkmann left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ahms5 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

f-brinkmann commented Apr 26, 2024

ahms5 commented Apr 29, 2024

f-brinkmann commented Apr 29, 2024

ahms5 commented Apr 29, 2024

f-brinkmann commented May 3, 2024

f-brinkmann commented Apr 20, 2024 •

edited