Skip to content

Commit 3fb2e11

Browse files
jasondamourjasondamour
committed
docs: update sphinx docs with package name and add contributing doc
1 parent 776b078 commit 3fb2e11

File tree

10 files changed

+315
-63
lines changed

10 files changed

+315
-63
lines changed

‎docs/Makefile‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ help:
1818
# Clean build directory
1919
clean:
2020
rm -rf $(BUILDDIR)
21-
rm -f cli-reference.md examples.md index.md installation.md
21+
rm -f *.md
2222

2323
# Build HTML documentation
2424
html:
@@ -32,5 +32,5 @@ markdown:
3232
@cp $(BUILDDIR)/markdown/*.md .
3333
@echo "Markdown files copied to docs/"
3434

35-
# Build both
35+
# Build both
3636
docs: markdown html

‎docs/contributing.md‎

Lines changed: 266 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
# Contributing to Lumos CLI
2+
3+
Thank you for your interest in contributing to the Lumos CLI! This document provides guidelines and instructions for contributors and maintainers.
4+
5+
## Development Setup
6+
7+
### Prerequisites
8+
9+
- Python 3.10.6 or higher
10+
- [uv](https://github.com/astral-sh/uv) (recommended) or pip
11+
12+
### Installation
13+
14+
1. Clone the repository:
15+
```bash
16+
git clone https://github.com/teamlumos/lumos-cli.git
17+
cd lumos-cli
18+
```
19+
2. Install dependencies with uv:
20+
```bash
21+
uv sync --group dev --group docs
22+
```
23+
3. Set up pre-commit hooks:
24+
```bash
25+
uv run pre-commit install
26+
```
27+
28+
### Running the CLI Locally
29+
30+
Create an alias for development:
31+
32+
```bash
33+
alias lumosdev='uv run python -m lumos'
34+
```
35+
36+
Or run directly:
37+
38+
```bash
39+
uv run python -m lumos --help
40+
```
41+
42+
## Project Structure
43+
44+
```default
45+
lumos-cli/
46+
├── src/lumos/ # Main source code
47+
│ ├── __init__.py
48+
│ ├── __main__.py # Entry point for `python -m lumos`
49+
│ ├── cli.py # Main CLI group and core commands
50+
│ ├── common/ # Shared utilities
51+
│ │ ├── client.py # API client
52+
│ │ ├── client_helpers.py
53+
│ │ ├── helpers.py # Authentication helpers
54+
│ │ ├── keyhelpers.py # Credential storage
55+
│ │ ├── logging.py # Debug logging
56+
│ │ └── models.py # Pydantic models
57+
│ ├── list_collections/ # `lumos list` subcommands
58+
│ │ └── cli.py
59+
│ └── request/ # `lumos request` subcommands
60+
│ └── cli.py
61+
├── tests/ # Test files
62+
├── docs/ # Sphinx documentation (auto-generated)
63+
├── sample-scripts/ # Example scripts for users
64+
├── pyproject.toml # Project configuration
65+
├── .releaserc.yaml # Semantic release configuration
66+
└── .github/workflows/ # CI/CD workflows
67+
```
68+
69+
## Development Workflow
70+
71+
### Creating a Branch
72+
73+
1. Create a feature branch from `main`:
74+
```bash
75+
git checkout -b feat/your-feature-name
76+
```
77+
2. Follow [Angular commit conventions](https://www.conventionalcommits.org/):
78+
- `feat:` - New features
79+
- `fix:` - Bug fixes
80+
- `docs:` - Documentation changes
81+
- `refactor:` - Code refactoring
82+
- `test:` - Adding or updating tests
83+
- `chore:` - Maintenance tasks
84+
85+
### Adding a New Command
86+
87+
1. Create a new module in the appropriate directory (e.g., `src/lumos/your_feature/cli.py`)
88+
2. Define your click command:
89+
```python
90+
from click_extra import command, option
91+
from lumos.common.helpers import authenticate
92+
93+
@command("your-command", help="Description of your command")
94+
@option("--flag", is_flag=True, help="Option description")
95+
@authenticate
96+
def your_command(flag: bool) -> None:
97+
"""Your command implementation."""
98+
pass
99+
```
100+
3. Register the command in `src/lumos/cli.py`:
101+
```python
102+
def register_subcommands():
103+
from lumos.your_feature.cli import your_command
104+
cli.add_command(your_command)
105+
```
106+
4. Add tests in `tests/`
107+
5. Update documentation in `docs/`
108+
109+
## Code Style
110+
111+
We use [ruff](https://github.com/astral-sh/ruff) for linting and formatting, and [basedpyright](https://github.com/DetachHead/basedpyright) for type checking.
112+
113+
### Running Linters
114+
115+
```bash
116+
# Run all checks
117+
uv run ruff check .
118+
uv run ruff format --check .
119+
uv run basedpyright
120+
121+
# Auto-fix issues
122+
uv run ruff check --fix .
123+
uv run ruff format .
124+
```
125+
126+
### Style Guidelines
127+
128+
- Maximum line length: 120 characters
129+
- Use double quotes for strings
130+
- Use type hints for all function parameters and return values
131+
- Follow PEP 8 naming conventions
132+
133+
## Testing
134+
135+
### Running Tests
136+
137+
```bash
138+
uv run pytest
139+
```
140+
141+
### Running Tests with Coverage
142+
143+
```bash
144+
uv run pytest --cov=lumos --cov-report=html
145+
```
146+
147+
### Writing Tests
148+
149+
- Place test files in the `tests/` directory
150+
- Name test files with `_test.py` suffix
151+
- Use descriptive test function names: `test_command_does_expected_behavior`
152+
153+
## Documentation
154+
155+
Documentation is built using [Sphinx](https://www.sphinx-doc.org/) with [MyST Markdown](https://myst-parser.readthedocs.io/) and [click-extra’s Sphinx extension](https://kdeldycke.github.io/click-extra/sphinx.html) for interactive CLI documentation with ANSI color support.
156+
157+
### Building Documentation Locally
158+
159+
```bash
160+
# Install docs dependencies
161+
uv sync --group docs
162+
163+
# Build both HTML and Markdown, copy markdown to docs/
164+
make -C docs docs
165+
166+
# Or build individually:
167+
make -C docs html # HTML only
168+
make -C docs markdown # Markdown only
169+
170+
# View the HTML docs
171+
open docs/sphinx/_build/html/index.html
172+
```
173+
174+
### Documentation Structure
175+
176+
Source files (in `docs/sphinx/`):
177+
178+
- `docs/sphinx/index.md` - Main landing page
179+
- `docs/sphinx/installation.md` - Installation instructions
180+
- `docs/sphinx/examples.md` - Usage examples with code samples
181+
- `docs/sphinx/cli-reference.md` - CLI reference with live examples (via click-extra sphinx)
182+
183+
Generated output:
184+
185+
- `docs/sphinx/_build/html/` - HTML documentation (deployed to GitHub Pages via semantic-release)
186+
- `docs/*.md` - Markdown documentation (copied from build, committed during releases)
187+
188+
### Using click-extra Sphinx Directives
189+
190+
The documentation uses click-extra’s Sphinx directives to show live CLI examples:
191+
192+
```markdown
193+
# Define CLI source (hidden by default)
194+
\`\`\`{click:source}
195+
:hide-results:
196+
from lumos.cli import cli
197+
\`\`\`
198+
199+
# Run CLI command and show output with ANSI colors
200+
\`\`\`{click:run}
201+
invoke(cli, args=["--help"])
202+
\`\`\`
203+
```
204+
205+
### Updating Documentation
206+
207+
1. **For CLI changes**: Update docstrings in the source code. The CLI reference uses `click:run` directives to execute commands and display their help.
208+
2. **For usage examples**: Edit `docs/examples.md` with new code samples.
209+
3. **For installation changes**: Update `docs/installation.md` and `README.md`.
210+
211+
## Release Process
212+
213+
Releases are automated via [semantic-release](https://semantic-release.gitbook.io/) and GitHub Actions.
214+
215+
### Triggering a Release
216+
217+
1. Go to the GitHub Actions page
218+
2. Select the “Release” workflow
219+
3. Click “Run workflow”
220+
4. Optionally enable “Dry run” to preview the release
221+
222+
### What Happens During Release
223+
224+
1. **Version Analysis**: semantic-release analyzes commits to determine the next version
225+
2. **Build**: Cross-platform binaries are built for Linux, macOS, and Windows
226+
3. **Documentation**: Documentation is regenerated with the new version
227+
4. **Release**:
228+
- `CHANGELOG.md` is updated
229+
- `pyproject.toml` version is bumped
230+
- Git tag is created
231+
- GitHub Release is published with binaries
232+
- Homebrew formula is updated
233+
234+
### Version Bumping
235+
236+
Version bumps are determined by commit messages:
237+
238+
- `feat:` → Minor version bump (e.g., 1.0.0 → 1.1.0)
239+
- `fix:` → Patch version bump (e.g., 1.0.0 → 1.0.1)
240+
- `BREAKING CHANGE:` in commit body → Major version bump (e.g., 1.0.0 → 2.0.0)
241+
242+
### Manual Release (Emergency)
243+
244+
If automated release fails:
245+
246+
```bash
247+
# Update version manually
248+
uv version X.Y.Z
249+
250+
# Build artifacts
251+
uv build
252+
uv run pyinstaller src/lumos/__main__.py
253+
254+
# Create and push tag
255+
git tag vX.Y.Z
256+
git push origin vX.Y.Z
257+
```
258+
259+
## Getting Help
260+
261+
- **Issues**: [GitHub Issues](https://github.com/teamlumos/lumos-cli/issues)
262+
- **Discussions**: [GitHub Discussions](https://github.com/teamlumos/lumos-cli/discussions)
263+
264+
## License
265+
266+
This project is licensed under the MIT License - see the LICENSE file for details.

‎docs/index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,3 +66,7 @@ lumos request
6666
* [`lumos request status`](cli-reference.md#lumos-request-status)
6767
* [`lumos request poll`](cli-reference.md#lumos-request-poll)
6868
* [`lumos request cancel`](cli-reference.md#lumos-request-cancel)
69+
70+
## Contributing
71+
72+
* [Contributing to Lumos CLI](contributing.md)

‎docs/installation.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ You can also install Lumos CLI as a Python package from GitHub Releases.
2525

2626
```bash
2727
# Download the wheel from the latest release
28-
pip install https://github.com/teamlumos/lumos-cli/releases/latest/download/lumos_cli-VERSION-py3-none-any.whl
28+
pip install https://github.com/teamlumos/lumos-cli/releases/latest/download/lumos-VERSION-py3-none-any.whl
2929
```
3030

3131
Replace `VERSION` with the actual version number from the [releases page](https://github.com/teamlumos/lumos-cli/releases).
@@ -34,7 +34,7 @@ Replace `VERSION` with the actual version number from the [releases page](https:
3434

3535
```bash
3636
# Install from GitHub releases
37-
uv tool install https://github.com/teamlumos/lumos-cli/releases/latest/download/lumos_cli-VERSION-py3-none-any.whl
37+
uv tool install https://github.com/teamlumos/lumos-cli/releases/latest/download/lumos-VERSION-py3-none-any.whl
3838
```
3939

4040
## Binary Downloads

‎docs/sphinx/cli-reference.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,7 @@ This page provides a complete reference for all Lumos CLI commands with live exa
44

55
```{click:source}
66
:hide-source:
7-
from lumos_cli.cli import lumos
8-
7+
from lumos.cli import lumos
98
```
109

1110
## Getting Help

‎docs/sphinx/conf.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,10 +19,10 @@
1919
# The version info, acts as replacement for |version| and |release|
2020
# Also used in various other places throughout the built documents.
2121
try:
22-
import tomllib
22+
import tomli
2323

2424
with open("../../pyproject.toml", "rb") as f:
25-
pyproject = tomllib.load(f)
25+
pyproject = tomli.load(f)
2626
version = pyproject["project"]["version"]
2727
release = version
2828
except Exception:

0 commit comments

Comments
 (0)