Fix bugs in documentation build

[ehennestad]

Motivation

Problem — the Sphinx docs build has warnings, but nothing catches them: they don't fail CI, and they don't fail the production Read the Docs build. Broken heading structure, mis-rendered docstrings, and unlisted pages can ship straight to the published docs with no signal to anyone.

Solution — fix the current set of warnings, then make both CI and the production RTD build fail whenever a Sphinx warning appears, so future regressions are caught before merge instead of shipping silently.

What changed

• Fixed a heading-level jump in untyped.rst (two subsections skipped a level)
• Marked how_to_cite.rst as :orphan: — it's only reached via direct links, not a toctree, so Sphinx was warning that it's unreachable from navigation
• Fixed reST-breaking auto-linked identifiers when immediately followed by punctuation from the schema text (e.g. a property name auto-linked right before = or [)
• Fixed the actual root cause of the OnePhotonSeries/TwoPhotonSeries data field warnings: the schema doc string for that field is valid reST as written, but file.internal.processDocstring was silently dropping the blank lines between its paragraphs while reflowing it into a MATLAB comment (default strsplit behavior), and a one-space indent mismatch in fillConstructor then broke the nested list alignment. Fixed both, and regenerated the two affected files
• Added .github/workflows/build_docs.yml: builds the docs on PRs/pushes touching docs/** or generated .m files, fails the job on any Sphinx warning
• Added fail_on_warning: true to .readthedocs.yaml so the production RTD build also fails on warnings

Implementation notes

Once the blank-line/indent bug above was fixed at the source, the docs-side workaround that had been reconstructing paragraph structure from the mangled text was no longer needed and was removed from docstring_processors.py. That file now only contains the one remaining fix needed for auto-linked identifiers next to punctuation, which is unrelated to the blank-line issue.

How to test

Run the Sphinx build with warnings treated as errors (sphinx-build -b html -W --keep-going docs/source docs/build/html, after running docs/source/sphinx_extensions/copy_files.py) and confirm it succeeds with no warnings. The new Build Sphinx docs CI check and the Read the Docs PR preview both do this automatically.

Checklist

• Have you ensured the PR description clearly describes the problem and solutions?
• Have you checked to ensure that there aren't other open or previously closed Pull Requests for the same change?
• If this PR fixes an issue, is the first line of the PR description fix #XX where XX is the issue number?

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.43%. Comparing base (13b0f9a) to head (b9eb091).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #849   +/-   ##
=======================================
  Coverage   95.43%   95.43%           
=======================================
  Files         228      228           
  Lines        8064     8064           
=======================================
  Hits         7696     7696           
  Misses        368      368           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.