docs: comprehensive documentation overhaul (#98) #215
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Delete legacy/docs/ (outdated API references) - Create docs/conf.py with autodoc, napoleon, intersphinx - Create docs/index.rst landing page with toctree - Add docs/requirements.txt for RTD build - Add placeholder index files for api/, tutorials/, examples/ Fixes broken ReadTheDocs build by providing missing conf.py. Legacy documentation referenced non-existent modules and was actively misleading users. Co-Authored-By: Claude Opus 4.5 <[email protected]>
- Generate API docs for 101 modules using sphinx-apidoc - Add missing __init__.py to 8 subpackages: - nuclear/isotopes/, sammy/io/, sammy/io/card_formats/ - sammy/fitting/, sammy/data/, sammy/results/ - experimental/, results/ - Organize docs/api/index.rst with logical module grouping - Document all major classes: SammyFactory, SammyRunner, IsotopeParameters, SpinGroups, file managers, etc. Build succeeds with 75 warnings (down from 198). Remaining warnings are Pydantic docstring style issues to be addressed in future cleanup. Co-Authored-By: Claude Opus 4.5 <[email protected]>
Enable `pip install .` in RTD build so autodoc can import pleiades modules. Without this, RTD builds produce empty module pages because the package is not installed. Co-Authored-By: Claude Opus 4.5 <[email protected]>
- Add autodoc-pydantic>=2.2.0 to docs/requirements.txt - Configure sphinxcontrib.autodoc_pydantic extension in conf.py - Enable field summaries, validators, and constraints display Pydantic models now show: - Field descriptions from Field(description="...") - Validator references and cross-links - Field type annotations with proper formatting Build succeeds with 275 warnings (up from 75 due to more comprehensive documentation of Pydantic internals). Co-Authored-By: Claude Opus 4.5 <[email protected]>
Add narrative documentation to complement API reference: - Installation guide with user/developer setup instructions - Quick start guide with minimal working example - SammyFactory workflow guide with complete execution pipeline - Backend selection guide with comparison and configuration Restructure main index with Getting Started, User Guides, and Reference sections. Co-Authored-By: Claude Opus 4.5 <[email protected]>
KedoKudo
changed the title
- Add warning docstring to nova_ornl.py module - Add warning to NovaSammyConfig class docstring - Add runtime UserWarning when NOVA backend is selected - Update backends.rst with warning box - Update quickstart.rst to note NOVA is paused - Update installation.rst NOVA section NOVA backend integration is paused while NOVA API stabilizes. Co-Authored-By: Claude Opus 4.5 <[email protected]>
Add 4 new user guides covering the complete analysis pipeline: - Input Preparation: data conversion, INP/PAR file generation, JsonManager configuration, SammyFilesMultiMode setup - ENDF Data: NuclearDataManager, automatic download, caching, supported libraries, IsotopeManager - Results Analysis: ResultsManager, LPT/LST parsing, plotting, chi-squared metrics, fitted parameter extraction - ORNL Data Processing: VENUS imaging data, normalization workflow, TOF-to-energy conversion, Transmission model Total: ~1,400 lines of documentation with 33 verified code examples. Also removes empty tutorials/examples placeholder sections. Co-Authored-By: Claude Opus 4.5 <[email protected]>
Delete auto-generated pleiades.rst which duplicated toctree entries already present in api/index.rst, causing 7 warnings. Also moves pleiades.post_install to Supporting Modules section. Co-Authored-By: Claude Opus 4.5 <[email protected]>
Collaborator
Author
|
Here is the RTD instance: https://pleiades-sammy.readthedocs.io/en/feature-98-sphinx-docs-infrastructure/installation.html |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Complete documentation overhaul for PLEIADES, establishing Sphinx/ReadTheDocs infrastructure and comprehensive user guides.
Phase 1: Sphinx Infrastructure (
9e1cb75)legacy/docs/containing outdated API referencesdocs/conf.pywith autodoc, napoleon, viewcode, intersphinx extensionsdocs/index.rstlanding page with toctree structuredocs/requirements.txtfor ReadTheDocs build dependenciesPhase 2: API Reference (
121504f,a0aa86f,fa82438)__init__.pyfiles to 8 subpackages for proper autodoc discovery.readthedocs.yamlfor autodoc to workPhase 3: User Guides (
50cdd44,d68fa9f)Created 10 user-facing documentation files:
installation.rst- User/developer setup, prerequisites, troubleshootingquickstart.rst- Minimal working example with SammyFactoryguides/sammy_workflow.rst- Complete execution pipeline, error handlingguides/backends.rst- Local/Docker/NOVA comparison and configurationguides/input_preparation.rst- Data format conversion, INP/PAR file generationguides/endf_data.rst- NuclearDataManager, ENDF retrieval, cachingguides/results_analysis.rst- ResultsManager, LPT/LST parsing, plottingguides/ornl_processing.rst- ORNL VENUS data processing workflowPhase 4: NOVA Backend Status (
bda4848)Marked NOVA backend as paused (API under development):
nova_ornl.pyNovaSammyConfigclass docstringUserWarningwhen NOVA backend is selectedPhase 5: Cleanup (
5037ca3)Test Plan
pixi run build-docssucceedsFiles Changed
__init__.pyfilesRelated
🤖 Generated with Claude Code
Co-Authored-By: Claude Opus 4.5 [email protected]