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

Remove API docs headers for functions, exceptions, and methods #948

Closed
Tracked by #479
Eric-Arellano opened this issue Mar 1, 2024 · 1 comment
Closed
Tracked by #479

Comments

@Eric-Arellano
Copy link
Collaborator

For functions, methods, and exceptions, we manually create h3 headers:

Screenshot 2024-03-01 at 4 33 18 PM

We do this so that:

  1. it shows up in the page ToC, since that is computed based on headers
  2. there's the little icon to make an anchor link
Screenshot 2024-03-01 at 4 34 45 PM

But we don't have to have a header for those two benefits; there are other ways we could get that. We can teach our page ToC to understand code objects, and we can add the little anchor icon to the code object directly.

Fixing this will remove duplication and get our design closer to qiskit-sphinx-theme, which we liked:

Screenshot 2024-03-01 at 4 36 36 PM

To implement this, we'll want MDX components like <Function>, which relates to the implementation for #735.

The trickiest part will be the page ToC. We need to make sure we consider the surrounding context like if the parent heading level.

@Eric-Arellano Eric-Arellano changed the title Remove manually created headers from API docs Remove API docs headers for functions, exceptions, and methods Mar 4, 2024
@Eric-Arellano
Copy link
Collaborator Author

We decided to not do this:

  1. We're making h3s larger soon and think it actually looks good when combined with the API docs redesign
Screenshot 2024-04-19 at 4 48 31 PM
  1. Figuring out the right page ToC is tricky, since it's based on h1-h6
  2. Figuring out the search index is tricky, since it differentiates between headers and non-headers
  3. It makes semantic sense to have the headers. It's helpful for screen readers and SEO

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Archived in project
Development

No branches or pull requests

2 participants