itsulu/itsulu-blog-publisher
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add comprehensive Blog Publisher documentation

Browse source 
Replace generic GitLab CI template with complete Odoo addon documentation
including features, installation, configuration, development workflow,
testing framework, Kubernetes CI/CD setup, and contributing guidelines.
This commit is contained in:
Nicholas Riegel 2026-05-29 21:52:59 -04:00
parent 34647c3742
commit 087c21a860
1 changed files with 175 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

209
README.md
View file

@ -1,52 +1,193 @@
# Gitlab component template # ITSulu Blog Publisher
<!-- AI-powered blog post generation for Odoo with multi-LLM support, scheduling, and social media integration.
Update this readme with your component details. Replace content in `< >` with your project information.
For more information:
- How to create a CI/CD component: https://docs.gitlab.com/ee/ci/components/#write-a-component ## Overview
- How to write a clear README.md file: https://docs.gitlab.com/ee/ci/components/#write-a-clear-readmemd
- CI/CD Component security best practices: https://docs.gitlab.com/ee/ci/components/#cicd-component-security-best-practices
-->
<!-- Uncomment and update the following link to display a release badge: https://docs.gitlab.com/ee/user/project/badges.html#latest-release-badges --> ITSulu Blog Publisher replaces fragile external blog-generation workflows with a fully server-side Odoo addon. Generate blog posts on-demand or on a schedule using Claude (Anthropic), OpenAI, Google Gemini, or Ollama. Posts are auto-populated with SEO metadata and social media copy, ready to publish.
<!-- [![Latest Release](https://gitlab.com/<your project path>/-/badges/release.svg)](https://gitlab.com/<your project path>/-/releases) -->
## Components ## Features
### `<Component-name>` - **Multi-LLM Support**: Anthropic Claude, OpenAI GPT, Google Gemini, Ollama / Open WebUI
- **Three Configurable Daily Slots**: morning, afternoon, evening — each with independent LLM provider + model selection
- **On-Demand & Scheduled Generation**: Backend wizard + website toolbar button + hourly cron dispatcher
- **Topic Queue**: Priority-ranked topic suggestions from ITSulu/company services
- **Single Structured-JSON LLM Call**: Lowest possible token usage — one API call returns title, body, SEO fields, tags, and social copy
- **Auto-Populated SEO**: meta title, description, keywords, tags
- **Social Media Copy**: X/Twitter (A+B), BlueSky (A+B), Mastodon, LinkedIn — platform-specific length limits
- **Notification Email**: Matches ITSulu Insights template format with social copy and source citations
- **Generation Log**: Full audit trail with token usage, duration, error messages, and retry button
- **Editable Prompt Templates**: System and user prompts in Settings UI
Use this component to `<component-description>`. ## Requirements
To add this component to your CI/CD pipeline, add the following include entry to your ### Odoo Version
project's CI/CD configuration: - **Target**: Odoo 17.0 Community (development branch)
- **Planned**: Odoo 14.0 Community (separate branch for App Store)
```yaml ### Python Dependencies
include: - `requests` (included in Odoo)
- component: https://gitlab.com/<your project path>/<name of your template>@<tag> - `anthropic` (for Anthropic Claude) — optional
- `openai` (for OpenAI) — optional
- `google-generativeai` (for Gemini) — optional
- Ollama uses OpenAI-compatible REST API (no SDK needed)
### Odoo Module Dependencies
- `base`
- `website`
- `website_blog`
- `mail`
- `base_setup`
## Installation
### From Source (Development)
```bash
# Clone the addon
git clone https://github.com/itsulu/itsulu-blog-publisher.git
cd itsulu-blog-publisher
# Copy addon into your Odoo addons path
cp -r addons/itsulu_blog_publisher /path/to/odoo/addons/
# Install via Odoo UI: Apps > Search "Blog Publisher" > Install
``` ```
Where `<tag>` is the release tag you want to use ([releases list](https://gitlab.com/<your-project-path>/-/releases)). ### Docker (Testing)
## Inputs ```bash
docker build -t itsulu-blog-publisher:latest .
docker run -p 8069:8069 itsulu-blog-publisher:latest
```
The template contains some optional [inputs](https://docs.gitlab.com/ee/ci/yaml/inputs.html): ## Configuration
<!-- Add or update rows if you change the inputs in the template --> 1. **Enable the addon**: Apps > Search "Blog Publisher" > Install
2. **Settings**: Go to Blog Publisher > Settings
- Set API keys for your LLM provider(s)
- Configure default LLM provider and model
- Set notification email recipients
- (Optional) Edit system and user prompt templates
3. **Create a blog**: Website > Blogs (if not already created)
4. **Schedule slots**: Blog Publisher > Schedule Slots
- Create or edit morning/afternoon/evening slots
- Select target blog, LLM provider + model, auto-publish
5. **Activate scheduling**: Set `active=True` on desired slots + enable the cron in Settings
| Input | Default value | Description | ## Usage
|------------|------------------|-------------|
| `job_name` | `job-template` | The job name. |
| `image` | `busybox:latest` | The container image to use to run the job. |
| `stage` | `test` | The stage name for the job. |
## Documentation ### Generate On-Demand
1. **From backend**: Blog Publisher > Generate Now (wizard selects topic, LLM, blog, tone)
2. **From website**: Visit your blog frontend, click "Generate Post" button in toolbar
3. **View result**: Blog Publisher > Generation Log (inspect token usage, errors, or publish)
This project includes a MVC structure to help you get started with [Gitlab CI/CD components](https://docs.gitlab.com/ee/ci/components/). ### Topic Queue
The template provides the basic file structure to create your own single component. - Blog Publisher > Topic Queue
This project should be public, or one of the jobs in the project's pipeline won't work. - Create topics with priority (low / normal / high / urgent)
- Scheduler pulls pending topics in priority order
- Mark used/skipped after generation
## Licence ### Scheduled Generation
- Enable the hourly cron: Settings > Blog Publisher > Activate Scheduling
- Each active slot (morning/afternoon/evening) triggers at configured UTC time
- Auto-publishes if `auto_publish=True`, otherwise in draft
The licence can be changed. By default this project has the [MIT Licence](./LICENCE). ## Development
<!-- You should update the year and name in the license file. -->
### Testing Framework
- **Unit tests**: `pytest-odoo` (TransactionCase)
- **BDD tests**: `pytest-bdd` (Gherkin features)
- **E2E tests**: Playwright (critical user journeys only)
Run tests locally:
```bash
# All tests
pytest addons/itsulu_blog_publisher/tests/ -v
# Single test class
pytest addons/itsulu_blog_publisher/tests/test_llm_router.py::TestLLMRouter -v
# With coverage
pytest addons/itsulu_blog_publisher/tests/ --cov=addons/itsulu_blog_publisher
# BDD features only
pytest addons/itsulu_blog_publisher/features/ -v
```
### Kubernetes CI/CD
The addon includes full Kubernetes test infrastructure:
- Template database priming (Odoo 17 init job)
- Ephemeral test job pods (auto-cleanup)
- PostgreSQL 15 persistent database
- GitLab Container Registry integration
See [kubernetes/itsulu-testing/README.md](kubernetes/itsulu-testing/README.md) for setup details.
## Architecture
See [ARCHITECTURE.md](ARCHITECTURE.md) for:
- Data model specifications
- LLM router design
- Generation orchestration flow
- Settings and notification email format
- CI/CD infrastructure
See [CLAUDE.md](CLAUDE.md) for:
- Odoo testing framework (TDD/BDD)
- Kubernetes test infrastructure gotchas
- Pre-commit hooks
- Failure recovery reference
## Contributing
We follow strict TDD discipline:
1. Write a failing test (show to reviewers)
2. Implement minimum code to pass
3. Refactor; test stays green
4. Run pre-commit hooks before submitting PR
All code contributions must:
- Have > 80% test coverage on new code
- Pass `pre-commit run --all-files`
- Follow PEP 8 (via black, isort, flake8)
- Include descriptive test names (not just "test1, test2")
See [CLAUDE.md](CLAUDE.md) for the complete TDD workflow.
## Roadmap
### Phase 1 (Current)
- ✅ Core generation orchestration
- ✅ Multi-LLM router
- ✅ Blog.post + social media model
- ✅ Schedule slots + cron dispatcher
- ✅ Settings + notification email
- ✅ Kubernetes test infrastructure
- 🔄 BDD/TDD test suite (in progress)
### Phase 2
- Image generation provider (DALL·E, Stable Diffusion)
- Coverage gates (≥80% on new code)
- Multi-language support
- Advanced scheduling (time zones, day-of-week patterns)
### Phase 3
- Playwright E2E journeys
- Performance regression testing
- Nightly smoke testing (CronJob)
- Runboat preview environment integration
## License
This addon is licensed under the LGPL v3.0. See [LICENSE](LICENSE) for details.
## Support
- **Issues**: https://github.com/itsulu/itsulu-blog-publisher/issues
- **Documentation**: See [CLAUDE.md](CLAUDE.md) and [ARCHITECTURE.md](ARCHITECTURE.md)
- **Testing Setup**: See [kubernetes/itsulu-testing/README.md](kubernetes/itsulu-testing/README.md)
## Authors
Built with ❤️ by [ITSulu](https://itsulu.com)