135 lines
3.8 KiB
Plaintext
135 lines
3.8 KiB
Plaintext
---
|
|
sidebar_label: Updating Documentation
|
|
sidebar_position: 99
|
|
---
|
|
|
|
# How to Update Documentation
|
|
|
|
This document explains the documentation system and procedures for updating {{PROJECT_TITLE}} documentation.
|
|
|
|
## Documentation Architecture
|
|
|
|
{{PROJECT_TITLE}} documentation is managed through a **centralized documentation system**:
|
|
|
|
```
|
|
~/PycharmProjects/project-docs/ # Central documentation hub
|
|
├── docs/projects/{{PROJECT_NAME}}/ # Docs source (THIS FOLDER)
|
|
├── scripts/build-public-docs.sh # Builds public docs
|
|
└── public-builds/{{PROJECT_NAME}}/ # Built static site
|
|
|
|
~/PycharmProjects/{{PROJECT_NAME}}/
|
|
└── docs -> ../project-docs/docs/projects/{{PROJECT_NAME}}/ # Symlink to here
|
|
```
|
|
|
|
## Two Documentation Modes
|
|
|
|
### Private Documentation (Internal)
|
|
|
|
- **Location**: `~/PycharmProjects/project-docs/`
|
|
- **View locally**: `cd ~/PycharmProjects/project-docs && npm start`
|
|
- **Contains**: All docs including credentials, internal notes, todos, deployment details
|
|
- **Audience**: Internal team only
|
|
|
|
### Public Documentation (Contributors)
|
|
|
|
- **Location**: `https://pages.brrd.tech/{{GITEA_OWNER}}/{{PROJECT_NAME}}/`
|
|
- **Build command**: `~/PycharmProjects/project-docs/scripts/build-public-docs.sh {{PROJECT_NAME}} --deploy`
|
|
- **Contains**: Only whitelisted public files
|
|
- **Audience**: Open-source contributors
|
|
|
|
## File Visibility Rules
|
|
|
|
### Automatically Public Files
|
|
|
|
These filenames are included in public builds:
|
|
- `overview.md`
|
|
- `architecture.md`
|
|
- `formats.md`
|
|
- `configuration.md`
|
|
- `index.md`
|
|
|
|
### Making Other Files Public
|
|
|
|
Add frontmatter to include a file in public builds:
|
|
|
|
```markdown
|
|
---
|
|
public: true
|
|
---
|
|
|
|
# Your Document Title
|
|
```
|
|
|
|
### Hiding Sections Within Public Files
|
|
|
|
Use HTML comments to hide sensitive sections:
|
|
|
|
```markdown
|
|
## Public Section
|
|
|
|
This content is visible to everyone.
|
|
|
|
<!-- PRIVATE_START -->
|
|
## Internal Notes
|
|
|
|
This section is stripped from public builds.
|
|
Credentials, internal discussions, etc.
|
|
<!-- PRIVATE_END -->
|
|
|
|
## Another Public Section
|
|
```
|
|
|
|
## Procedures
|
|
|
|
### Adding New Documentation
|
|
|
|
1. Create the file in `~/PycharmProjects/project-docs/docs/projects/{{PROJECT_NAME}}/`
|
|
2. Add appropriate frontmatter (title, sidebar position)
|
|
3. If it should be public, either:
|
|
- Use a whitelisted filename, OR
|
|
- Add `public: true` to frontmatter
|
|
4. Preview locally: `cd ~/PycharmProjects/project-docs && npm start`
|
|
|
|
### Updating Existing Documentation
|
|
|
|
1. Navigate via symlink: `cd ~/PycharmProjects/{{PROJECT_NAME}}/docs`
|
|
- Or directly: `cd ~/PycharmProjects/project-docs/docs/projects/{{PROJECT_NAME}}`
|
|
2. Edit the relevant `.md` file
|
|
3. Preview locally if needed
|
|
|
|
### Publishing to Public Site
|
|
|
|
```bash
|
|
# Build and deploy {{PROJECT_NAME}} docs only
|
|
~/PycharmProjects/project-docs/scripts/build-public-docs.sh {{PROJECT_NAME}} --deploy
|
|
|
|
# Or build all projects
|
|
~/PycharmProjects/project-docs/scripts/build-public-docs.sh --deploy
|
|
|
|
# Dry run (see what would happen)
|
|
~/PycharmProjects/project-docs/scripts/build-public-docs.sh {{PROJECT_NAME}} --dry-run
|
|
```
|
|
|
|
### Viewing Documentation
|
|
|
|
```bash
|
|
# Private docs (all content)
|
|
cd ~/PycharmProjects/project-docs && npm start
|
|
# Opens http://localhost:3000
|
|
|
|
# Public docs
|
|
# Visit https://pages.brrd.tech/{{GITEA_OWNER}}/{{PROJECT_NAME}}/
|
|
```
|
|
|
|
## For AI Assistants
|
|
|
|
When asked to update documentation for this project:
|
|
|
|
1. **DO** edit files in `docs/` (the symlink) or the full path above
|
|
2. **DO NOT** create documentation files in the project root
|
|
3. **DO** use appropriate visibility (public/private) based on content
|
|
4. **DO** run the build script if publishing changes to the public site
|
|
5. **DO** preview changes locally before publishing
|
|
|
|
The `docs/` folder you see in this project is a symlink to the central documentation system. All changes are reflected in both the private hub and (after building) the public site.
|