Review and update documentation after numpy-backed API changes

[wilsonfreitas]

Summary

The documentation currently has two separate problems:

1. The Sphinx build is blocked by stale path assumptions in docs/source/conf.py and by invoking make -C docs html outside the uv environment.
2. The published documentation content has drifted from the current numpy-backed public API after the project-structure move, the packaged-calendar migration from .cal to .json, and the newer Calendar.load signature.

Findings

• make -C docs html fails in the current shell because docs/Makefile calls sphinx-build directly instead of going through uv.
• uv run make -C docs html fails immediately in docs/source/conf.py because it still copies notebooks from repo-root paths like ../../pandas.ipynb, but those notebooks were moved out of the root in 9f9679a (Organized project structure).
• After temporarily supplying the expected notebook paths, Sphinx completes but emits warnings/errors that show API drift:
  • docs/source/api.rst still documents getdate and getbizdays, but the public bizdays.Calendar no longer has those members.
  • bizdays/calendar.py docstrings currently emit docutils errors for numpy.int_ / numpy.bool_.
  • docs/source/_static is referenced but missing.
• The docs content is materially stale:
  • notebooks and docs still use Calendar.load("ANBIMA") and Calendar.load("PMC/NYSE") positionally, but the current public API is keyword-only (name= / filename=).
  • notebooks still use Calendar.load(filename='ANBIMA.cal'), but packaged calendars were migrated to JSON in 3aa16d3; that example now fails.
  • set_option('mode', 'pandas') still exists, but it no longer changes the return type of the top-level numpy-backed Calendar methods.
  • index.md, quick.ipynb, getdate.ipynb, pandas.ipynb, and SITE.ipynb still teach getdate / getbizdays, which are legacy-only now.

Review tracks

1. Build pipeline and source layout

• Decide the canonical way to build docs (uv run make -C docs html or a Makefile wrapper that is environment-aware).
• Remove the stale copy-from-root behavior in docs/source/conf.py.
• Choose one notebook source of truth: notebooks/ or docs/source/, then eliminate the duplicated copy flow.
• Audit static asset paths such as _static.

2. Public API documentation alignment

• Re-document the current top-level bizdays.Calendar as the numpy-backed implementation.
• Remove or clearly separate legacy-only members (getdate, getbizdays, pandas-mode behavior).
• Update signatures and examples for Calendar.load(name=...), Calendar.load(filename=...), and PMC/....
• Fix docstrings/types that currently generate Sphinx parsing errors.

3. Example and notebook migration

• Audit every notebook and Markdown example for:
  • keyword-only Calendar.load
  • .cal vs JSON/custom-file loading
  • current return types (numpy.datetime64 / arrays) instead of legacy datetime.date expectations
  • removed legacy methods
• Decide whether notebooks should be executable documentation or archival examples.
• If executable, define which examples must run in CI and which may stay illustrative.

4. Legacy story and migration guidance

• Decide what remains supported as legacy compatibility (get_option / set_option) versus what should be called out as historical behavior.
• Add an explicit migration guide from legacy docs/examples to the numpy-backed API.
• Link that migration guidance from README, docs index, and API reference.

5. Validation strategy

• Add a reliable docs build command to CI after the content update is complete.
• Consider a lightweight example-validation pass for the examples that are intended to stay current.

Suggested execution order

1. Stabilize the docs build path and notebook source layout.
2. Define the public-vs-legacy documentation boundary.
3. Update API reference and top-level README/index pages.
4. Migrate notebooks/examples in batches.
5. Add docs validation in CI once the content is aligned.

Notes

• The current docs build does not protect against stale notebook code because nbsphinx is rendering existing notebook content rather than failing on outdated examples.
• The docs review should cover both docs/source/** and the parallel notebook/Markdown surfaces (notebooks/**, index.md, README.md).

[wilsonfreitas]

Documentation review and rewrite plan

Problem

The current documentation set is partially aligned with the NumPy-backed API, but
it still falls short in the areas you called out:

• legacy topics still appear in normal user-facing docs
• there is no proper “build a Calendar from scratch” walkthrough
• the JSON calendar layout is only hinted at, not explained
• pandas usage is under-documented
• the API reference relies too heavily on autodoc without method-by-method examples
• packaged calendars are mentioned, but not presented clearly as a supported set
• the migration guide is too thin and still mixes in legacy compatibility notes

Validated scope

• Normal docs should describe only the current public API.
• get_option / set_option should be removed from user-facing docs and kept, if
  needed, only as migration context.
• Calendar.getdate remains part of the public API and should stay documented.

Proposed approach

1. Reframe the docs information architecture around the current API only.

   • Keep the public entry points centered on bizdays.Calendar.
   • Split conceptual docs from reference docs more clearly.
   • Move any unavoidable legacy discussion into the migration guide only.

2. Add a full “creating calendars” narrative.

   • Show Calendar(...) from scratch with holidays, weekdays, startdate,
     enddate, name, and financial.
   • Add a separate section for Calendar.load(...).
   • Explain the distinction between constructing in memory and loading from JSON.

3. Add first-class JSON documentation.

   • Document each JSON field and expected types.
   • Show a minimal file and a fuller example.
   • Explain when filename= should be used versus packaged name=....

4. Expand examples and reference coverage.

   • Provide pandas examples that show accepted inputs and current NumPy-native
     outputs.
   • Add a packaged-calendars section covering ANBIMA, B3, Actual, and the
     optional PMC/... integration.
   • Rewrite the API reference so each Calendar method has an explanation and at
     least one example of typical usage.

5. Rewrite the migration guide in detail.

   • Explain positional Calendar.load(...) to keyword-only usage.
   • Explain packaged .cal examples versus packaged JSON resources.
   • Explain old expectations around return types versus current NumPy-backed
     behavior.
   • Explain what to do instead of legacy-only topics that are being removed from
     normal docs.

Planned documentation structure

• index.rst: concise overview plus a cleaner docs map
• quick.ipynb: current quickstart only
• calendars.ipynb: packaged calendars, creating a calendar from scratch, and
  loading from JSON
• pandas.ipynb: pandas-oriented examples that emphasize current outputs
• getdate.ipynb: focused getdate usage
• api.rst: curated method-by-method reference with examples, not just raw autodoc
• migration.rst: the only place where legacy migration is discussed
• README.md and index.md: top-level mirrors of the same current-API story

Todos

• Restructure the docs outline so current API topics are clearly separated by
  tutorial, reference, and migration content.
• Rewrite the API reference to document each Calendar method with examples and
  remove normal-doc references to legacy runtime options.
• Rewrite tutorial notebooks/pages to cover:
  • creating a Calendar from scratch
  • JSON layout and file-based loading
  • packaged calendars
  • pandas examples
• Expand the migration guide with concrete before/after examples and replacement
  guidance.
• Reconcile README and site index with the same documentation boundary.
• Validate the resulting docs build and project checks after implementation.

Notes

• The current docs build is already stable, so this phase is content-focused.
• The rewrite should optimize for user guidance first, with autodoc supporting the
  reference rather than defining it.

[wilsonfreitas]

Progress update:

• Pushed commit 762d0cc (Refresh NumPy-backed documentation) to branch feature/typing.
• Reworked the docs around the current NumPy-backed API only.
• Added constructor-based calendar creation, JSON layout guidance, packaged calendar coverage, expanded pandas examples, a method-by-method API reference, and a more detailed migration guide.
• Updated the docs build path so Sphinx runs through uv and executes the tracked notebooks under docs/source/.

Keeping this issue open as requested.