Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[WIP] Adopt new docspec and integrate with Novella #245

Merged
merged 67 commits into from Feb 28, 2022

Conversation

NiklasRosenstein
Copy link
Owner

@NiklasRosenstein NiklasRosenstein commented Feb 23, 2022

Goal of this PR is to

  • Adopt to new docspec 2.x API that is currently WIP
  • Integrate with Novella
    • Implement a basic version of the @pydoc tag
    • Update SinglePageRenderer interface (or add a new interface) for rendering single docspec objects (instead of only a module)
    • Make a resolver separately configurable (as it is not provided through SinglePageRenderer and it wouldn't make much sense for it to have such a capability)
    • Make MarkdownRenderer produce Novella @anchor tags
    • Make CrossRefProcessor procuce Novella {@link} tags
    • (Option to) hide the module name when referencing it with the @pydoc tag? (If yes, maybe we should include the module name somewhere else in the generated documentation for the module members)
    • Automatically detect source linker configuration if possible
    • Add an option to use anchor HTML tags instead of Markdown header IDs for links between API objects (maybe enabled by default) because the IDs for Markdown headers might not be unique (e.g. two API objects with the same name in the same page)
  • Make codebase fully typed
  • Update Pydoc-Markdown's own documentation to be built with Novella (the latest can be found on GitHub pages: https://niklasrosenstein.github.io/pydoc-markdown/)

Late state considerations:

  • Work on making Novella Python 3.7 3.8-3.9 compatible? (Currently it is only compatible with 3.10)

If you are interested in an introduction to how the new system works, check out the Using Novella guide in the documentation.

@NiklasRosenstein NiklasRosenstein marked this pull request as ready for review February 23, 2022 23:12
@NiklasRosenstein NiklasRosenstein marked this pull request as draft February 23, 2022 23:12
@NiklasRosenstein NiklasRosenstein marked this pull request as ready for review February 28, 2022 22:20
@NiklasRosenstein NiklasRosenstein merged commit 46eddae into develop Feb 28, 2022
@NiklasRosenstein NiklasRosenstein deleted the adopt-new-docspec branch February 28, 2022 22:20
@NiklasRosenstein NiklasRosenstein restored the adopt-new-docspec branch February 28, 2022 22:26
@NiklasRosenstein NiklasRosenstein mentioned this pull request Feb 28, 2022
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.

--dump throws exception when any class has any doc comments
1 participant