You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
3
+
This file provides guidance to Claude Code when working with the OpenSPP documentation repository.
4
4
5
5
## Overview
6
6
7
7
This is the documentation repository for OpenSPP - an open-source social protection platform. The documentation is built using Sphinx with MyST parser for Markdown support.
8
8
9
+
## Project Structure
10
+
11
+
```
12
+
docs/
13
+
├── overview/ # High-level information for decision makers
14
+
│ ├── features/ # Feature overviews by functional area
-`update_navigation.py` - Navigation menu management
94
-
-`update_links.py` - Cross-reference link updating
95
-
96
-
## Key Development Notes
97
-
98
-
- The documentation uses Sphinx 4.5.0 with MyST parser for Markdown support
99
-
- Vale is configured for style checking with OpenSPP-specific vocabulary
100
-
- The build system automatically handles Odoo module documentation integration
101
-
- Live reload development server runs on port 8050
102
-
- GitHub Actions handle automated builds and deployment on push to main branch
103
-
- Redirects are managed using sphinx-reredirects extension (currently disabled due to version conflicts)
104
-
105
-
## Module Documentation
106
-
107
-
When documenting OpenSPP modules, follow the existing pattern in `docs/reference/modules/`. Each module should have its own Markdown file with standardized sections for overview, features, configuration, and usage.
108
-
109
-
## Managing Redirects
110
-
111
-
When moving or renaming documentation pages, add redirects in `docs/conf.py`:
112
-
```python
113
-
redirects = {
114
-
"old-path": "new-path.html",
115
-
}
73
+
## Documentation Standards
74
+
75
+
When working with documentation:
76
+
77
+
1.**File Format**: All documentation uses MyST Markdown (.md files)
78
+
2.**Metadata**: Every page MUST have MyST frontmatter with html_meta for SEO
79
+
3.**Headings**: Use sentence case (e.g., "Getting started" not "Getting Started")
80
+
4.**Links**:
81
+
- Use `{doc}` for internal documentation links
82
+
- Link to module reference pages when mentioning modules
83
+
- Link to product pages when mentioning SP-MIS, Social Registry, or Farmer Registry
84
+
- Never put links or `:term:` in headings
85
+
5.**Terminology**: Use `:term:` only on first occurrence of glossary terms
86
+
87
+
Example frontmatter:
88
+
```yaml
89
+
---
90
+
myst:
91
+
html_meta:
92
+
"title": "Page Title"
93
+
"description": "Brief description for SEO"
94
+
"keywords": "OpenSPP, relevant, keywords"
95
+
---
116
96
```
117
-
Note: The sphinx-reredirects extension is currently disabled due to version conflicts with Sphinx 4.5.0. The redirect mappings are prepared in conf.py but commented out until a compatible version is available.
118
97
119
-
## Documentation Refactoring Lessons Learned
98
+
## Common Tasks
99
+
100
+
### Adding a New Documentation Page
101
+
1. Create the .md file in the appropriate directory
102
+
2. Add required MyST frontmatter with html_meta
103
+
3. Add the page to the appropriate index.md toctree
104
+
4. Use sentence case for all headings
105
+
5. Run `make html` to verify it builds
120
106
121
-
### Automated Migration Approach
107
+
### Updating Module Documentation
108
+
- Module docs are in `docs/reference/modules/`
109
+
- Each module has its own .md file named after the module
110
+
- Include sections: Overview, Features, Configuration, Usage
122
111
123
-
The 2025 documentation restructuring used Python scripts for automation:
124
-
-**refactor_docs.py**: Main script for moving files and handling merges/splits
125
-
-**update_navigation.py**: Updates toctree entries in index files
-**Cross-Reference Complexity**: Internal links need careful updating across all files
146
-
-**Image Path Management**: Images need to move with their content while maintaining relative paths
133
+
- Documentation uses Sphinx 4.5.0 with MyST parser
134
+
- Vale is configured with Microsoft and alex style guides
135
+
- Live reload server runs on port 8050
136
+
- GitHub Actions handle automated builds on push to main
137
+
- The build warns about missing files but usually succeeds
147
138
148
-
When performing future refactoring, use the existing scripts as templates and follow the phased approach documented in `review_work/doc_migration_guide.md`.
0 commit comments