Closed mcarans closed 2 years ago
Hey @mcarans!
Can I simply add tags at the bottom of main.md for the various API pages like "Configuration" that you can see below so that they appear under "API Documentation" in the menu on the left as now, or do I have to make one markdown page for each API page (I hope not as that would be a lot of tiny repetitive md files)?
Good question! I've been expecting this one to come up and been thinking about it for a while. I'm not entirely sure yet about the extend to which these files should be generated for you automatically, i.e. where is the line between power & control vs. ease of use.
For now, I've made a change to Novella 0.1.14 that allows you to create a custom action with your own logic that can be used to generate the files before the Markdown preprocessor runs (which includes Pydoc-Markdown).
I've added an example to the Novella documentation here: https://niklasrosenstein.github.io/novella/concepts/#actions
Currently, the @pydoc
tag does not understand wildcards but only full object identifiers, so in the example above I put the module name hdx.api.configuration
instead of hdx.api.configuration.*
into the file.
Let me know what you think, absolutely open for input here.
Where does the configuration go like loaders, renderer and source_linker or is that not needed any more?
The answer here is mostly "no". The PydocTagProcessor
that you enable with the use "pydoc"
statement in the Novella build script is a bit more opinionated and applies some heuristics compared to the old-style Pydoc-Markdown YAML configuration.
PythonLoader
by default that is initialized with sensible default search paths{@link}
tagsMarkdownRenderer
with some parameters changed by default
It looks like you're making some major changes. How do I replicate my simple setup with the old pydoc-markdown of a main.md and the generated API documentation from the TOML description? (In readthedocs, it looks like this.) Can I simply add tags at the bottom of main.md for the various API pages like "Configuration" that you can see below so that they appear under "API Documentation" in the menu on the left as now, or do I have to make one markdown page for each API page (I hope not as that would be a lot of tiny repetitive md files)? Where does the configuration go like loaders, renderer and source_linker or is that not needed any more?
My pyproject.toml looks like this: