Skip to content

feat: replace mkdocs with pdoc for API docs, add pytest-html-plus with BDD docstrings#19

Merged
nullhack merged 1 commit intomainfrom
feat/pdoc-html-plus-docs
Apr 3, 2026
Merged

feat: replace mkdocs with pdoc for API docs, add pytest-html-plus with BDD docstrings#19
nullhack merged 1 commit intomainfrom
feat/pdoc-html-plus-docs

Conversation

@nullhack
Copy link
Copy Markdown
Owner

@nullhack nullhack commented Apr 3, 2026

Summary

  • Replace mkdocs/mkdocstrings with pdoc for API documentation
  • Add pytest-html-plus for BDD-style HTML test reports
  • Update conftest.py to extract and display Given/When/Then docstrings in HTML
  • Add doc-publish task to push API docs to GitHub Pages

Changes

Documentation

  • pyproject.toml: Replace pdoc dependencies, update doc-serve/doc-build/doc-publish tasks
  • README.md: Update doc commands, change coverage path to docs/coverage

Testing

  • Add tests/conftest.py with BDD docstring extraction and HTML regeneration
  • Update pyproject.toml for pytest-html-plus with JSON report
  • Add BDD docstring guidelines to TDD skill

Removed

  • Delete docs/mkdocs.yaml and docs/docs/ (mkdocs config)
  • Remove mkdocs dependencies from pyproject.toml

…h BDD docstrings

- Replace mkdocs/mkdocstrings with pdoc for API documentation
- Add pytest-html-plus for BDD-style HTML test reports
- Add conftest.py to extract and display Given/When/Then docstrings
- Update README with new doc commands (doc-serve, doc-build, doc-publish)
- Add BDD docstring guidelines to TDD skill
- Update coverage path to docs/coverage (from docs/htmlcov)
- Add doc-publish task to push API docs to GitHub Pages
@nullhack
Copy link
Copy Markdown
Owner Author

nullhack commented Apr 3, 2026

PR Review

Verified the following changes work correctly:

Template Generation

  • cookiecutter generates project successfully with all new files

Dependencies

  • pdoc, pytest-html-plus, pytest-mock installed correctly

Tests

  • task test passes with 10 tests, 100% coverage
  • BDD docstrings display in HTML report (19 occurrences of 'Given:')
  • Line breaks render correctly (<br> in HTML)

Documentation

  • task doc-build generates docs/api/index.html with search
  • task doc-serve serves pdoc locally
  • README updated with new doc commands

Code Quality

  • No linting issues

Recommendation: Merge and release.

@nullhack nullhack merged commit 66a92ec into main Apr 3, 2026
@nullhack nullhack deleted the feat/pdoc-html-plus-docs branch April 3, 2026 04:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant