Qiskit / Qiskit/documentation

Spellcheck API docs

Open
#818 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

infra 🏗️ needs discussion 💬
Dominant language
Jupyter Notebook
Stars
106
Forks
223
Avg merge
1d 8h
Merged PRs (30d)
72

Description

We currently ignore API docs:

https://github.com/Qiskit/documentation/blob/be5918995fa62cfef8f6ad6ee5b92553b7c5faae/cSpell.json#L278-L283

While we can't easily control them*, they are still important parts of the documentation! We should aim to have no spelling issues. Some thoughts on how to approach this:

  • Should we add cspell to the source repositories? That's useful so that they detect the problems more quickly. It is annoying to add to their workflow and have to duplicate cSpell.json, though, to allow-list words.
  • We need an ignore mechanism for API docs. Ideally we can do that without changing cSpell.json; it doesn't work to add inline comments to the markdown. I'm wondering if we can instead ignore via our custom script.
  • When adding, we should keep the default npm run check:spelling to ignore API docs, per the spirit of https://github.com/Qiskit/documentation/pull/792.

*Note that we can make changes to historical API docs safely, if we're confident we won't add new versions of the API docs from CI. That is, if we're confident they're the final docs for that release series.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read cSpell.json around lines 278-283 and the custom spelling-check script, then run npm run check:spelling to understand the current behavior. Compare the proposed source-repository and API-doc handling approaches; done means API docs can be checked without breaking the default command's intended exclusions.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, tooling
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.