2052709 - nss doc: convert from rst to md

Status: RESOLVED FIXED

(NSS :: Documentation, task)

Description

[Sylvestre Ledru [:Sylvestre]]

This to be able to remove rst support from the fx tree
and that md is now more popular

Comment 1

[Sylvestre Ledru [:Sylvestre]]

Attachment: Bug 2052709 - Convert documentation from reStructuredText to Markdown (automated). r?#nss-reviewers

Automated conversion of all doc/rst/**/*.rst files to MyST-flavored
Markdown using rst-to-myst. This is the raw tool output, plus the
minimal Sphinx configuration needed to parse the result:

• Enable the myst_parser extension and register .md as the source
  suffix in doc/rst/conf.py.
• Rewrite intra-doc toctree entries from .rst to .md.

Subsequent commits fix the build warnings and apply markdownlint.

Comment 2

[Sylvestre Ledru [:Sylvestre]]

Attachment: Bug 2052709 - Fix Markdown documentation build warnings. r?#nss-reviewers

Bring the converted docs to a clean Sphinx build (0 errors, 0 warnings):

• conf.py: suppress myst.xref_missing (cross-references to Firefox-managed
  docs outside the standalone build, previously covered by ref.ref).
• legacy/jss: restore RST link-target definitions inside the eval-rst grid
  table so its references resolve.
• Escape regex/grammar brackets ([abc], [^a-z], grammar productions) that
  Markdown would otherwise parse as links/footnotes.
• certificate_download_specification: use plain code fences for the
  BEGIN/END CERTIFICATE samples.
• Reconstruct the sample2 / sample3 pages that the converter emitted empty.
• Give the colliding auto-generated release-note anchors unique names.

Also update tooling so future docs stay Markdown and CI keeps building:

• taskcluster docs image installs myst-parser.
• generate_release_doc.py / nss-release-helper.py emit MyST Markdown.
• Update .rst references in the release README and runbook.

Comment 3

[Sylvestre Ledru [:Sylvestre]]

Attachment: Bug 2052709 - Apply markdownlint to the converted Markdown docs. r?#nss-reviewers

• Add doc/rst/.markdownlint.jsonc, disabling rules that do not fit
  MyST/Sphinx content (MD013 line-length, MD041 first-line-heading,
  MD051 link-fragments, MD033 inline-HTML; MD024 siblings-only).
• Run markdownlint --fix across doc/rst (trailing spaces, blank-line
  spacing around lists/fences, list markers, etc.).
• Escape leading '#' on wrapped prose and shell command/comment lines
  (e.g. "PKCS #5", "# pk12util ...") that Markdown would otherwise
  render as spurious headings, and fence the #include example in
  nss_tech_note4. These were genuine rendering regressions.

This takes markdownlint from 15454 default-config errors to 99. The
remainder are stylistic/legacy-content items (bare code-fence languages,
ordered-list numbering, hr style) left for follow-up. Sphinx still builds
with 0 errors / 0 warnings.

Comment 4

[Sylvestre Ledru [:Sylvestre]]

Attachment: Bug 2052709 - Rename doc/rst to doc/src and update references. r?#nss-reviewers

Comment 5

[Sylvestre Ledru [:Sylvestre]]

Attachment: Bug 2052709 - Convert NSS 3.126 release notes to Markdown r?#nss-reviewers

Upstream added doc/rst/releases/nss_3_126.rst after the RST->Markdown
conversion branch was created. Convert it to Markdown to match the rest
of the docs and wire it into the release notes index.

Comment 6

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/projects/nss/rev/fc52c169c7a2
Convert documentation from reStructuredText to Markdown (automated). r=nss-reviewers,jschanck
https://hg.mozilla.org/projects/nss/rev/e675ebd9709e
Fix Markdown documentation build warnings. r=nss-reviewers,jschanck
https://hg.mozilla.org/projects/nss/rev/e4129541a92c
Apply markdownlint to the converted Markdown docs. r=nss-reviewers,jschanck
https://hg.mozilla.org/projects/nss/rev/01d005506044
Rename doc/rst to doc/src and update references. r=nss-reviewers,jschanck
https://hg.mozilla.org/projects/nss/rev/88411b72a5bf
Convert NSS 3.126 release notes to Markdown