OWASP / OWASP/pytm

Docs: Replace pdoc3 with Zensical, provide a project + API documentation

Open
#352 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
1.2k
Forks
229
PR merge metrics
No merged PRs in 30d

Description

pdoc3 is pretty limited and not really a state of the art tool for automated API and project documentation anymore.

So far a kind of de-facto standard for modern Python project documentation including automatic API generation has been MKDocs + Material for MKDocs + mkdocstrings for quite some years.

Zensical is the new tool that deprecates MkDocs + Material for MKDocs which will go into maintenance mode as mkdocstrings will. Zensical is developed by the same team as Material for MKDocs and mkdocstrings is and improves design wise limitations of the MKDocs based documentation tech stack.

Zensical almost reached feature parity with Material for MKDocs, supports mkdocsstrings already (until there is added a Zensical-"native" mkdocstrings replacement?) and aims at being backwards compatible.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the repository's existing pdoc3 documentation setup and the linked Zensical compatibility documentation. Define how project and automatic API documentation should be provided, then verify that the completed migration produces both documentation types with the intended navigation and design.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.