Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add import name #485

Merged
merged 5 commits into from
Nov 6, 2024
Merged

Add import name #485

merged 5 commits into from
Nov 6, 2024

Conversation

FoamyGuy
Copy link
Contributor

@FoamyGuy FoamyGuy commented Nov 5, 2024

resolves: #462

here is a screenshot of the built docs page built from drivers.rst with the new import names added:
image

Note that some lines already had something else in parenthesis so now there are two parenthesized items for them.

I did attempt the other style with the code syntax, but as far as I can tell this doesn't seem to be possible within a toctree definition for sphinx. I tried a few different ways to format it, but all of them caused the link to get broken and show the full URL and angle brackets on the page. The only docs I could find are here: https://sphinx-doc-zh.readthedocs.io/en/latest/markup/toctree.html

It doesn't have much specific info about the required syntax used but mentions that it's "similar to rst links"
image

The shortnames used are "naively" constructed by prepending "adafruit_" to the short name found in the docs URL. The two libraries that I changed manually were neopixel and neopixel_spi which don't have the leading adafruit_. I'm not aware of any other libraries that are like that, but if there are any they will be wrong in this file currently.

I've also checked in the script used to generate these changes, I'm not sure if we would want to keep it or not. It assumes the old format of drivers.rst and has no logic to prevent adding more copies of the import name so if drivers.rst is updated then this script wouldn't really useful beyond historical context without further changes.

This script is meant to run as a "one shot" and I've committed the results here. Moving forward PRs would need to include this import name with the line that they commit into drivers.rst. Perhaps it could be automated with actions, but I didn't pursue that avenue, if it's something we'd like to do I could look into it.

Copy link
Contributor

@dhalbert dhalbert left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for doing this! I wondered if it could be done at generation time, but this is fine.

I suggested changes for a few more libraries that have non-standard names.

docs/drivers.rst Outdated Show resolved Hide resolved
docs/drivers.rst Outdated Show resolved Hide resolved
docs/drivers.rst Outdated Show resolved Hide resolved
docs/drivers.rst Outdated Show resolved Hide resolved
@FoamyGuy
Copy link
Contributor Author

FoamyGuy commented Nov 6, 2024

@dhalbert Thank you! those are all updated with the latest commit.

@dhalbert dhalbert merged commit 99c6f7f into adafruit:main Nov 6, 2024
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

docs/drivers.rst does not include import name
2 participants