Documentation sidebar restructuring

[dana-gill]

Reference Issue

Fixes #1478

What does this implement/fix? Explain your changes.

This restructures the Core IO section of documentation sidebar. Core IO no longer exists and is replaced by the following:

• Signals (includes load, stream, resample, and any signal generators and helper utilities)
• Spectral representations
• Magnitude scaling
• Unit conversion (time, frequency)
• Music notation
• Pitch and tuning
• Harmonics
• Phase recovery
• Miscellaneous (collects current misc + frequency range generators)

Any other comments?

None

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.75%. Comparing base (8dae20c) to head (0120fcd).
Report is 7 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1801      +/-   ##
==========================================
- Coverage   98.77%   98.75%   -0.03%     
==========================================
  Files          34       35       +1     
  Lines        4666     4641      -25     
==========================================
- Hits         4609     4583      -26     
- Misses         57       58       +1     

Flag	Coverage Δ
unittests	98.75% <ø> (-0.03%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[bmcfee]

Rebasing this from main should fix the build issues.

[dana-gill]

Alright @bmcfee, apologies for the delay, here is the PR :)

[bmcfee]

Thanks @dana-gill !

A couple of broad comments:

• Can you rebase this on the current main? I made a couple of changes to the environment and sphinx config lately that this is presently reverting.
• The new structure has lost the autosummary / menu list of subsection contents, eg https://librosa.org/doc/latest/core.html . Can we recover that?
• We've also lost the module-level docstring, and the linter is now complaining about it.
• I don't think it's correct to directly include generated contents (eg in harmonics.rst). Is there a way to keep this as using autodoc/ autosummary, but just break out the sections differently from what we had before? I think this should be as simple as keeping the module-level docstring in __init__.py, but just reorganizing the section information in the autosummary. Maybe I'm missing something?

[dana-gill]

Can you rebase this on the current main? I made a couple of changes to the environment and sphinx config lately that this is presently reverting.

Huh, I thought I rebased it already. These are the commands I ran:

$ git fetch --all
$ git rebase origin/main

And it says Current branch documentation_sidebar_restructuring is up to date.. Are there any specific commands I should run for the repo?

The new structure has lost the autosummary / menu list of subsection contents, eg https://librosa.org/doc/latest/core.html . Can we recover that?

Yes we can 🥳 Just to make sure I understand you: You would like to the sidebar to have both the content of Core IO and DSP and the following (ie: How the branch looks now):

Signals (includes load, stream, resample, and any signal generators and helper utilities)
Spectral representations
Magnitude scaling
Unit conversion (time, frequency)
Music notation
Pitch and tuning
Harmonics
Phase recovery
Miscellaneous (collects current misc + frequency range generators)

Let me know if I understood that properly.

We've also lost the module-level docstring, and the linter is now complaining about it.

To make sure I understand: The linter would like librosa/__init__.py to stay the same and all of this should remain the same? https://github.com/librosa/librosa/blob/main/librosa/__init__.py#L3-L210

I don't think it's correct to directly include generated contents (eg in harmonics.rst). Is there a way to keep this as using autodoc/ autosummary, but just break out the sections differently from what we had before? I think this should be as simple as keeping the module-level docstring in init.py, but just reorganizing the section information in the autosummary. Maybe I'm missing something?

I need to do a bit more digging for this 😅 I think there was a reason why I couldn't just keep using autosummary, but I would have do some experimentations and get back to you.

[bmcfee]

You would like to the sidebar to have both the content of Core IO and DSP and the following (ie: How the branch looks now):

Signals (includes load, stream, resample, and any signal generators and helper utilities) Spectral representations Magnitude scaling Unit conversion (time, frequency) Music notation Pitch and tuning Harmonics Phase recovery Miscellaneous (collects current misc + frequency range generators)

Let me know if I understood that properly.

Currently all of those things are buried under the "Core IO and DSP" heading, which is not too accurate of a descriptor at this point. I think the idea here was to lift up the sub-headings of core (currently "audio loading", "time-domain processing", etc) to the top-level and eliminate the "core IO and dsp" section, along with some restructuring of the topics to make it a bit more navigable (as you describe).

To make sure I understand: The linter would like librosa/__init__.py to stay the same and all of this should remain the same? https://github.com/librosa/librosa/blob/main/librosa/__init__.py#L3-L210

Well the linter wants some docstring in the top-level module, but it doesn't necessarily care about the contents. In light of the above though, I think what we can do is just drop the "Core IO and DSP" heading, then replace the --- (second-level subheadings) by === (first-level headings) along with some reorganization as noted above. We shouldn't really need to change anything outside of __init__.py to get the new sidebar structure.

All that said, we should also while we're here consider #1823 - this AFAIK would just entail fleshing out the docstring for the core module with some descriptive text beyond just the menu headings. Also happy to take that up in a separate issue to keep things simple.

[dana-gill]

You would like to the sidebar to have both the content of Core IO and DSP and the following (ie: How the branch looks now):
Signals (includes load, stream, resample, and any signal generators and helper utilities) Spectral representations Magnitude scaling Unit conversion (time, frequency) Music notation Pitch and tuning Harmonics Phase recovery Miscellaneous (collects current misc + frequency range generators)
Let me know if I understood that properly.

Currently all of those things are buried under the "Core IO and DSP" heading, which is not too accurate of a descriptor at this point. I think the idea here was to lift up the sub-headings of core (currently "audio loading", "time-domain processing", etc) to the top-level and eliminate the "core IO and dsp" section, along with some restructuring of the topics to make it a bit more navigable (as you describe).

To make sure I understand: The linter would like librosa/__init__.py to stay the same and all of this should remain the same? https://github.com/librosa/librosa/blob/main/librosa/__init__.py#L3-L210

Well the linter wants some docstring in the top-level module, but it doesn't necessarily care about the contents. In light of the above though, I think what we can do is just drop the "Core IO and DSP" heading, then replace the --- (second-level subheadings) by === (first-level headings) along with some reorganization as noted above. We shouldn't really need to change anything outside of __init__.py to get the new sidebar structure.

All that said, we should also while we're here consider #1823 - this AFAIK would just entail fleshing out the docstring for the core module with some descriptive text beyond just the menu headings. Also happy to take that up in a separate issue to keep things simple.

Ahh. So you would like the sidebar to look how it looks like in this PR and also have core.html at the same time?

I also did some investigation to see if it was possible to edit only the __init__.py and not add anrst files. It is, but you will have the plus icons on the left side. If that works with you, then I can make the changes :)

All that said, we should also while we're here consider #1823 - this AFAIK would just entail fleshing out the docstring for the core module with some descriptive text beyond just the menu headings. Also happy to take that up in a separate issue to keep things simple.

Sure! I can make that part of the PR.

[bmcfee]

Ahh. So you would like the sidebar to look how it looks like in this PR and also have core.html at the same time?

Yeah I suppose so. core.html is autogenerated from the top-level package import, ie the docstring in librosa/__init__.py, so all we're really talking about here is promoting the sub-headings within core up a level by changing the formatting.

I also did some investigation to see if it was possible to edit only the __init__.py and not add anrst files. It is, but you will have the plus icons on the left side. If that works with you, then I can make the changes :)

Yeah, that's totally fine! Thanks.

[bmcfee]

👋 @dana-gill just checking in to see how you're doing on this? It's the last PR we need to put in before pushing out the 0.10.2 release, so if there's anything I can do to help get it moving, please let me know.

[dana-gill]

👋 @dana-gill just checking in to see how you're doing on this? It's the last PR we need to put in before pushing out the 0.10.2 release, so if there's anything I can do to help get it moving, please let me know.

Hey Brian! Thanks for checking in. I've been incredibly swamped with work so I don't think this will make it to the 0.10.2 release. Is that okay?

[bmcfee]

Ok, no worries! I'll make some today to sort out what actually needs to be there from what's a nice-to-have, and take this one out of the critical path.