docs refactor
All checks were successful
All checks were successful
This commit is contained in:
594
docs/content/develop/index.md
Normal file
594
docs/content/develop/index.md
Normal file
@ -0,0 +1,594 @@
|
||||
---
|
||||
version: "1.0"
|
||||
date: "2025-01-15"
|
||||
author: "DWS Foldsite Team"
|
||||
title: "Develop Foldsite"
|
||||
description: "Contributing to Foldsite development"
|
||||
summary: "Guidelines for contributing code, documentation, themes, and ideas to the Foldsite project."
|
||||
quick_tips:
|
||||
- "Start with documentation or small bug fixes"
|
||||
- "Discuss major changes in issues before implementing"
|
||||
- "Follow existing code style and patterns"
|
||||
---
|
||||
|
||||
# Develop Foldsite
|
||||
|
||||
Want to contribute to Foldsite? We welcome contributions of all kinds!
|
||||
|
||||
## Ways to Contribute
|
||||
|
||||
### 1. Documentation
|
||||
|
||||
**Impact:** High | **Difficulty:** Low
|
||||
|
||||
Improving documentation helps everyone:
|
||||
|
||||
- Fix typos and unclear explanations
|
||||
- Add missing examples
|
||||
- Create tutorials
|
||||
- Translate to other languages
|
||||
|
||||
**How to start:**
|
||||
1. Find documentation that confused you
|
||||
2. Fork the repository
|
||||
3. Edit markdown files in `docs/content/`
|
||||
4. Submit pull request
|
||||
|
||||
No coding required!
|
||||
|
||||
### 2. Bug Fixes
|
||||
|
||||
**Impact:** High | **Difficulty:** Low to Medium
|
||||
|
||||
Fix issues others are experiencing:
|
||||
|
||||
- Browse [GitHub Issues](https://github.com/DWSresearch/foldsite/issues)
|
||||
- Look for "good first issue" label
|
||||
- Fix the bug
|
||||
- Add test if possible
|
||||
- Submit pull request
|
||||
|
||||
### 3. New Features
|
||||
|
||||
**Impact:** High | **Difficulty:** Medium to High
|
||||
|
||||
Add new capabilities:
|
||||
|
||||
- Discuss in issue first
|
||||
- Get feedback on approach
|
||||
- Implement feature
|
||||
- Add documentation
|
||||
- Add tests
|
||||
- Submit pull request
|
||||
|
||||
### 4. Templates & Themes
|
||||
|
||||
**Impact:** Medium | **Difficulty:** Medium
|
||||
|
||||
Create reusable designs:
|
||||
|
||||
- Build complete theme
|
||||
- Document installation
|
||||
- Submit to theme gallery
|
||||
- Help others customize
|
||||
|
||||
### 5. Testing
|
||||
|
||||
**Impact:** Medium | **Difficulty:** Low
|
||||
|
||||
Help ensure quality:
|
||||
|
||||
- Test new releases
|
||||
- Report bugs with details
|
||||
- Verify fixes work
|
||||
- Test on different platforms
|
||||
|
||||
## Development Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Python 3.10 or higher
|
||||
- Git
|
||||
- Text editor or IDE
|
||||
|
||||
### Getting Started
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://github.com/DWSresearch/foldsite.git
|
||||
cd foldsite
|
||||
|
||||
# Create virtual environment
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate # On Windows: venv\Scripts\activate
|
||||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Install development dependencies
|
||||
pip install -r requirements-dev.txt # If exists
|
||||
|
||||
# Run tests
|
||||
python -m pytest # If tests exist
|
||||
|
||||
# Run Foldsite
|
||||
python main.py --config config.toml
|
||||
```
|
||||
|
||||
### Development Workflow
|
||||
|
||||
1. **Create branch** for your changes:
|
||||
```bash
|
||||
git checkout -b feature/my-feature
|
||||
```
|
||||
|
||||
2. **Make changes** following code style
|
||||
|
||||
3. **Test changes**:
|
||||
```bash
|
||||
# Manual testing
|
||||
python main.py --config config.toml
|
||||
|
||||
# Run tests if available
|
||||
python -m pytest
|
||||
```
|
||||
|
||||
4. **Commit changes**:
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Add feature: description"
|
||||
```
|
||||
|
||||
5. **Push and create PR**:
|
||||
```bash
|
||||
git push origin feature/my-feature
|
||||
```
|
||||
|
||||
## Code Style
|
||||
|
||||
### Python
|
||||
|
||||
Follow [PEP 8](https://pep8.org/) with these specifics:
|
||||
|
||||
**Formatting:**
|
||||
- 4 spaces for indentation
|
||||
- Max line length: 100 characters
|
||||
- Use type hints where helpful
|
||||
- Docstrings for public functions
|
||||
|
||||
**Example:**
|
||||
|
||||
```python
|
||||
def render_page(
|
||||
path: Path,
|
||||
base_path: Path = Path("./"),
|
||||
template_path: Path = Path("./"),
|
||||
) -> str:
|
||||
"""
|
||||
Renders a web page based on the provided path.
|
||||
|
||||
Args:
|
||||
path: The path to the target file or directory
|
||||
base_path: The base path for relative paths
|
||||
template_path: Path to directory containing templates
|
||||
|
||||
Returns:
|
||||
Rendered HTML content of the page
|
||||
"""
|
||||
# Implementation...
|
||||
```
|
||||
|
||||
**Naming:**
|
||||
- `snake_case` for functions and variables
|
||||
- `PascalCase` for classes
|
||||
- `UPPER_CASE` for constants
|
||||
|
||||
### HTML Templates
|
||||
|
||||
- 2 spaces for indentation
|
||||
- Close all tags
|
||||
- Use semantic HTML
|
||||
- Comment complex logic
|
||||
|
||||
```html
|
||||
<article class="post">
|
||||
{% if metadata %}
|
||||
<h1>{{ metadata.title }}</h1>
|
||||
|
||||
{# Loop through tags #}
|
||||
{% if metadata.tags %}
|
||||
<div class="tags">
|
||||
{% for tag in metadata.tags %}
|
||||
<span class="tag">{{ tag }}</span>
|
||||
{% endfor %}
|
||||
</div>
|
||||
{% endif %}
|
||||
{% endif %}
|
||||
</article>
|
||||
```
|
||||
|
||||
### CSS
|
||||
|
||||
- 2 spaces for indentation
|
||||
- Alphabetical property order (within reason)
|
||||
- Mobile-first responsive design
|
||||
- BEM naming for classes (optional but encouraged)
|
||||
|
||||
```css
|
||||
.post {
|
||||
margin: 2rem 0;
|
||||
padding: 1rem;
|
||||
}
|
||||
|
||||
.post__title {
|
||||
font-size: 2rem;
|
||||
font-weight: bold;
|
||||
margin-bottom: 1rem;
|
||||
}
|
||||
|
||||
@media (min-width: 768px) {
|
||||
.post {
|
||||
margin: 3rem 0;
|
||||
padding: 2rem;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### Key Components
|
||||
|
||||
**main.py**
|
||||
- Entry point
|
||||
- Initializes configuration
|
||||
- Registers template helpers
|
||||
- Starts server
|
||||
|
||||
**src/config/**
|
||||
- Configuration loading
|
||||
- Command-line argument parsing
|
||||
|
||||
**src/server/**
|
||||
- Flask application setup
|
||||
- Route registration
|
||||
- File manager (admin interface)
|
||||
|
||||
**src/routes/**
|
||||
- URL routing logic
|
||||
- Path validation and security
|
||||
- Content serving
|
||||
|
||||
**src/rendering/**
|
||||
- Template discovery
|
||||
- Markdown rendering
|
||||
- Page rendering pipeline
|
||||
- Helper functions
|
||||
|
||||
### Request Flow
|
||||
|
||||
```
|
||||
1. HTTP Request
|
||||
↓
|
||||
2. Flask routes (/src/routes/routes.py)
|
||||
↓
|
||||
3. Path validation & security checks
|
||||
↓
|
||||
4. Template discovery (/src/rendering/template_discovery.py)
|
||||
↓
|
||||
5. Content rendering (/src/rendering/renderer.py)
|
||||
↓
|
||||
6. Template rendering with Jinja2
|
||||
↓
|
||||
7. HTTP Response
|
||||
```
|
||||
|
||||
### Adding a New Template Helper
|
||||
|
||||
Template helpers are functions available in all templates.
|
||||
|
||||
**1. Add to TemplateHelpers class** (`src/rendering/helpers.py`):
|
||||
|
||||
```python
|
||||
class TemplateHelpers:
|
||||
def __init__(self, config: Configuration):
|
||||
self.config = config
|
||||
|
||||
def get_my_helper(self, param: str) -> list:
|
||||
"""
|
||||
Description of what this helper does.
|
||||
|
||||
Args:
|
||||
param: Description of parameter
|
||||
|
||||
Returns:
|
||||
Description of return value
|
||||
"""
|
||||
# Implementation
|
||||
result = []
|
||||
# ... logic ...
|
||||
return result
|
||||
```
|
||||
|
||||
**2. Register in main.py**:
|
||||
|
||||
```python
|
||||
server.register_template_function("get_my_helper", t.get_my_helper)
|
||||
```
|
||||
|
||||
**3. Use in templates**:
|
||||
|
||||
```jinja
|
||||
{% for item in get_my_helper('value') %}
|
||||
{{ item }}
|
||||
{% endfor %}
|
||||
```
|
||||
|
||||
**4. Document** in `docs/content/templates/template-helpers.md`
|
||||
|
||||
## Testing
|
||||
|
||||
### Manual Testing
|
||||
|
||||
Create test content:
|
||||
|
||||
```
|
||||
test-site/
|
||||
├── content/
|
||||
│ ├── index.md
|
||||
│ ├── test-post.md
|
||||
│ └── photos/
|
||||
│ └── test.jpg
|
||||
├── templates/
|
||||
│ ├── base.html
|
||||
│ └── __file.md.html
|
||||
└── styles/
|
||||
└── base.css
|
||||
```
|
||||
|
||||
Run and verify:
|
||||
```bash
|
||||
python main.py --config test-config.toml
|
||||
```
|
||||
|
||||
### Writing Tests
|
||||
|
||||
*Note: Test infrastructure may need to be set up*
|
||||
|
||||
Example test structure:
|
||||
|
||||
```python
|
||||
# tests/test_renderer.py
|
||||
import pytest
|
||||
from pathlib import Path
|
||||
from src.rendering.renderer import render_page
|
||||
|
||||
def test_render_simple_markdown():
|
||||
"""Test rendering a basic markdown file"""
|
||||
# Setup
|
||||
content = Path("test-content/simple.md")
|
||||
templates = Path("test-templates")
|
||||
|
||||
# Execute
|
||||
result = render_page(content, template_path=templates)
|
||||
|
||||
# Assert
|
||||
assert "<h1>" in result
|
||||
assert "<!DOCTYPE html>" in result
|
||||
```
|
||||
|
||||
## Pull Request Guidelines
|
||||
|
||||
### Before Submitting
|
||||
|
||||
- [ ] Code follows style guidelines
|
||||
- [ ] Changes are focused (one feature/fix per PR)
|
||||
- [ ] Commit messages are clear
|
||||
- [ ] Documentation updated if needed
|
||||
- [ ] Manual testing completed
|
||||
- [ ] No merge conflicts
|
||||
|
||||
### PR Description Template
|
||||
|
||||
```markdown
|
||||
## Description
|
||||
Brief description of changes
|
||||
|
||||
## Type of Change
|
||||
- [ ] Bug fix
|
||||
- [ ] New feature
|
||||
- [ ] Documentation
|
||||
- [ ] Refactoring
|
||||
- [ ] Other (describe)
|
||||
|
||||
## Testing
|
||||
How you tested the changes
|
||||
|
||||
## Screenshots
|
||||
If UI changes, add screenshots
|
||||
|
||||
## Checklist
|
||||
- [ ] Code follows project style
|
||||
- [ ] Self-reviewed code
|
||||
- [ ] Commented complex code
|
||||
- [ ] Updated documentation
|
||||
- [ ] No breaking changes (or documented)
|
||||
```
|
||||
|
||||
### Review Process
|
||||
|
||||
1. **Maintainer reviews** code and design
|
||||
2. **Feedback provided** if changes needed
|
||||
3. **Discussion** on approach if necessary
|
||||
4. **Approval** when ready
|
||||
5. **Merge** by maintainer
|
||||
|
||||
Be patient - maintainers are volunteers.
|
||||
|
||||
## Issue Guidelines
|
||||
|
||||
### Bug Reports
|
||||
|
||||
Use this template:
|
||||
|
||||
```markdown
|
||||
**Foldsite Version:** X.X.X
|
||||
**Python Version:** X.X.X
|
||||
**OS:** macOS/Linux/Windows
|
||||
|
||||
**Description:**
|
||||
Clear description of the bug
|
||||
|
||||
**Steps to Reproduce:**
|
||||
1. Step one
|
||||
2. Step two
|
||||
3. See error
|
||||
|
||||
**Expected Behavior:**
|
||||
What should happen
|
||||
|
||||
**Actual Behavior:**
|
||||
What actually happens
|
||||
|
||||
**Error Messages:**
|
||||
```
|
||||
Paste full error/traceback
|
||||
```
|
||||
|
||||
**Additional Context:**
|
||||
Any other relevant information
|
||||
```
|
||||
|
||||
### Feature Requests
|
||||
|
||||
Use this template:
|
||||
|
||||
```markdown
|
||||
**Feature Description:**
|
||||
Clear description of the feature
|
||||
|
||||
**Use Case:**
|
||||
Why you need this feature
|
||||
|
||||
**Proposed Implementation:**
|
||||
Ideas for how it could work (optional)
|
||||
|
||||
**Alternatives Considered:**
|
||||
Other solutions you've thought about
|
||||
|
||||
**Additional Context:**
|
||||
Examples, mockups, etc.
|
||||
```
|
||||
|
||||
## Communication
|
||||
|
||||
### GitHub Issues
|
||||
|
||||
- **Bugs** - Report problems
|
||||
- **Features** - Request improvements
|
||||
- **Questions** - Ask for help (or use Discussions)
|
||||
|
||||
### GitHub Discussions
|
||||
|
||||
- **Q&A** - Get help using Foldsite
|
||||
- **Ideas** - Discuss potential features
|
||||
- **Show and Tell** - Share what you built
|
||||
- **General** - Everything else
|
||||
|
||||
### Response Times
|
||||
|
||||
- **Critical bugs** - Few days
|
||||
- **Other issues** - 1-2 weeks
|
||||
- **Feature requests** - Varies
|
||||
- **PRs** - 1-2 weeks
|
||||
|
||||
## Security
|
||||
|
||||
### Reporting Vulnerabilities
|
||||
|
||||
**Do not** open public issues for security problems.
|
||||
|
||||
Email: security@dws.rip
|
||||
|
||||
Include:
|
||||
- Description of vulnerability
|
||||
- Steps to reproduce
|
||||
- Potential impact
|
||||
- Suggested fix (if you have one)
|
||||
|
||||
### Security Considerations
|
||||
|
||||
When contributing:
|
||||
|
||||
- Validate all file paths
|
||||
- Sanitize user inputs
|
||||
- Be careful with path traversal
|
||||
- Don't expose sensitive info in errors
|
||||
- Follow principle of least privilege
|
||||
|
||||
## Project Philosophy
|
||||
|
||||
Keep these in mind when contributing:
|
||||
|
||||
### 1. Simplicity
|
||||
|
||||
Prefer simple solutions over complex ones. Add complexity only when necessary.
|
||||
|
||||
### 2. Convention Over Configuration
|
||||
|
||||
Sensible defaults that work for most cases. Configuration for edge cases.
|
||||
|
||||
### 3. User Focus
|
||||
|
||||
Optimize for content creators, not developers. Make common tasks easy.
|
||||
|
||||
### 4. Clear Over Clever
|
||||
|
||||
Code should be understandable. Clever tricks make maintenance harder.
|
||||
|
||||
### 5. Backward Compatibility
|
||||
|
||||
Don't break existing sites without very good reason and clear migration path.
|
||||
|
||||
## Resources
|
||||
|
||||
### Learning
|
||||
|
||||
- **Python** - [docs.python.org](https://docs.python.org/)
|
||||
- **Flask** - [flask.palletsprojects.com](https://flask.palletsprojects.com/)
|
||||
- **Jinja2** - [jinja.palletsprojects.com](https://jinja.palletsprojects.com/)
|
||||
|
||||
### Tools
|
||||
|
||||
- **VS Code** - Great Python support with extensions
|
||||
- **PyCharm** - Full-featured Python IDE
|
||||
- **Git** - Version control
|
||||
- **GitHub CLI** - Command-line GitHub interface
|
||||
|
||||
## Recognition
|
||||
|
||||
Contributors are recognized:
|
||||
|
||||
- **README** - Listed in contributors section
|
||||
- **Release notes** - Mentioned in changelogs
|
||||
- **Commits** - Your name in git history
|
||||
- **Gratitude** - Appreciation from the community!
|
||||
|
||||
## Getting Help
|
||||
|
||||
Stuck on contribution?
|
||||
|
||||
- **Read existing code** - Learn from examples
|
||||
- **Ask in Discussions** - Community can help
|
||||
- **Open draft PR** - Get early feedback
|
||||
- **Reach out** - DWS team is friendly!
|
||||
|
||||
## Next Steps
|
||||
|
||||
- **Browse issues** - Find something to work on
|
||||
- **Read the code** - Understand how it works
|
||||
- **Make a change** - Start small
|
||||
- **Submit PR** - Share your contribution!
|
||||
|
||||
Thank you for helping make Foldsite better!
|
||||
|
||||
**Remember:** Every contribution matters, from fixing a typo to adding major features. We appreciate all help!
|
||||
Reference in New Issue
Block a user