Skip to content

Docs improvements: referencing #2798

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.

Sign up for GitHub

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

Jump to bottom
Merged
harshil21 merged 16 commits into from
Jan 22, 2022
Merged

Docs improvements: referencing #2798

harshil21 merged 16 commits into from
Jan 22, 2022

Conversation

@Bibo-Joshi
Copy link
Member

@Bibo-Joshi Bibo-Joshi commented Nov 28, 2021 •
edited by harshil21
Loading

  • bump sphinx
  • try to render base classes better
  • use sphinx-paramref to make parameters referencable
  • use nitpicky mode for sphinx
  • add new CI task to build the docs

Checklist for PRs

  • Added .. versionadded:: version, .. versionchanged:: version or .. deprecated:: version to the docstrings for user facing changes (for methods/class descriptions, arguments and attributes)
  • Created new or adapted existing unit tests
  • Added myself alphabetically to AUTHORS.rst (optional)
  • Added new classes & modules to the docs

@Bibo-Joshi Bibo-Joshi added the ⚙️ documentation affected functionality: documentation label Nov 28, 2021
@Bibo-Joshi Bibo-Joshi added this to the v14 milestone Nov 28, 2021
github-actions[bot]
github-actions bot reviewed Nov 28, 2021
View reviewed changes
Copy link

@github-actions github-actions bot left a comment

Choose a reason for hiding this comment

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

Hey! Looks like you edited the (dev) requirements or the pre-commit hooks. I'm just a friendly reminder to keep the pre-commit hook versions in sync with the dev requirements and the additional dependencies for the hooks in sync with the requirements :)

@Bibo-Joshi Bibo-Joshi changed the base branch from doc-fixes to asyncio November 28, 2021 20:20
@Bibo-Joshi Bibo-Joshi changed the base branch from asyncio to doc-fixes November 28, 2021 20:20
@Bibo-Joshi Bibo-Joshi marked this pull request as ready for review November 29, 2021 19:36
@Bibo-Joshi Bibo-Joshi changed the title WIP: Docs improvements: referencing Docs improvements: referencing Nov 29, 2021
harshil21
harshil21 requested changes Nov 30, 2021
View reviewed changes
Copy link
Member

@harshil21 harshil21 left a comment

Choose a reason for hiding this comment

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

Nice job! There's probably more places we can use paramref but for now this is a good start.

Can you build docs for this branch? I want to verify the 'hover' of paramrefs work fine on mobile

@Bibo-Joshi
Copy link
Member Author

Bibo-Joshi commented Nov 30, 2021

Thanks for the review! Thorough as usual :) Didn't look at the CSS stuff yet though

Built docs are at https://python-telegram-bot.readthedocs.io/en/docs-referencing/

@Bibo-Joshi Bibo-Joshi mentioned this pull request Dec 1, 2021
Closed
@Bibo-Joshi
Copy link
Member Author

Bibo-Joshi commented Dec 1, 2021

Openend a PR at sqlalchemyorg/sphinx-paramlinks#13 for better nitpicky support and making parameter names the links

Base automatically changed from doc-fixes to v14 December 13, 2021 17:21
@Bibo-Joshi Bibo-Joshi changed the base branch from v14 to doc-fixes December 13, 2021 18:21
@Bibo-Joshi Bibo-Joshi mentioned this pull request Dec 14, 2021
Closed
24 tasks
Base automatically changed from doc-fixes to v14 January 3, 2022 08:09
@Bibo-Joshi Bibo-Joshi changed the base branch from v14 to doc-fixes January 3, 2022 11:54
@harshil21
Copy link
Member

harshil21 commented Jan 3, 2022

While at it, we can also use nitpicky mode by default in the Makefile

@Bibo-Joshi
Copy link
Member Author

Bibo-Joshi commented Jan 4, 2022

I added nitpicky = True to docs/source/conf.py. that should suffice, I guess 🤔

harshil21
harshil21 reviewed Jan 7, 2022
View reviewed changes
harshil21
harshil21 reviewed Jan 7, 2022
View reviewed changes
Copy link
Member

@harshil21 harshil21 left a comment

Choose a reason for hiding this comment

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

some missed ones from the earlier review:

@harshil21
Copy link
Member

harshil21 commented Jan 22, 2022

might be worth to check how this looks in the new furo theme. Also I'm okay with merging this for now, hard to keep track of what is fixed and what isn't

@Bibo-Joshi
Copy link
Member Author

Bibo-Joshi commented Jan 22, 2022

From this thread, two PRs were made at sphinx-paramlinks:

  1. allow to customize how the link for the parameters is displayed
  2. make sphinx-paramlinks support the nitpicky mode

The first is already merged, but there's no new release yet. The second is not yet merged.
I've updated the dependency to install from the current commit on sphinx-pl/master, which inludes 1 and changed the style so that the parameter names are clickable as discussed above.
IMO the nitpicky support is not very urgent, which is why I didn't put my fork as dependency.

@harshil21 harshil21 merged commit a7f8038 into doc-fixes Jan 22, 2022
@harshil21 harshil21 deleted the docs-referencing branch January 22, 2022 20:08
@github-actions github-actions bot locked and limited conversation to collaborators Jan 30, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Reviewers

@harshil21 harshil21 harshil21 requested changes

@github-actions github-actions[bot] github-actions[bot] left review comments

@Poolitzer Poolitzer Awaiting requested review from Poolitzer

Assignees

No one assigned

Labels

⚙️ documentation affected functionality: documentation

Projects

None yet

Milestone

v20.0a0

Development

Successfully merging this pull request may close these issues.

3 participants

@Bibo-Joshi @harshil21