Skip to content

feat: document docs generation process and improve missing docs UX#3471

Merged
sabine merged 1 commit intomainfrom
feat-document-docs-generation
Feb 25, 2026
Merged

feat: document docs generation process and improve missing docs UX#3471
sabine merged 1 commit intomainfrom
feat-document-docs-generation

Conversation

@cuihtlauac
Copy link
Collaborator

Summary

  • Add "Automatic Documentation Generation" section to the /packages page explaining how package documentation is generated
  • Improve the "documentation not found" error page with better guidance

Changes

/packages page

Added a new section explaining:

  • How documentation is generated using odoc
  • The role of ocaml-docs-ci in automatically building docs
  • Brief mention of OCurrent as the underlying technology
  • Tips for writing good documentation

Documentation not found page

  • Changed title from "Page not found" to "Documentation not found" (more specific)
  • Added explanation that docs are generated by ocaml-docs-ci
  • Changed "Open an Issue" button to "Report Missing Docs" linking to ocaml-docs-ci issues
  • Pre-fills the issue with package name and version for easier reporting

Screenshots

Would be helpful to add screenshots after testing locally.

Test plan

  • Build locally with make build
  • Visit /packages and verify the new section renders correctly
  • Navigate to a package with missing docs and verify:
    • The error message is clear
    • The "Report Missing Docs" button opens a pre-filled GitHub issue

🤖 Generated with Claude Code

- Add "Automatic Documentation Generation" section to /packages page
  explaining how odoc, ocaml-docs-ci, and OCurrent work together
- Improve the "documentation not found" page:
  - Change title from "Page not found" to "Documentation not found"
  - Explain that docs are generated by ocaml-docs-ci
  - Link to ocaml-docs-ci issue tracker instead of ocaml.org issues
  - Pre-fill issue with package name and version

This helps users understand the documentation infrastructure and
directs them to the right place when documentation is missing.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Copy link
Collaborator

@sabine sabine left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

significant improvement

before after
Screenshot 2026-02-25 at 15-58-12 dream 1 0 0~alpha8 · OCaml Package Screenshot 2026-02-25 at 15-58-00 dream 1 0 0~alpha8 · OCaml Package

@sabine sabine merged commit e99091a into main Feb 25, 2026
5 checks passed
@sabine sabine deleted the feat-document-docs-generation branch February 25, 2026 14:59
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.

2 participants