Question: how do I replicate old pydoc-markdown setup with Novella?

[mcarans]

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:

[[tool.pydoc-markdown.loaders]]
type = "python"
search_path = ["src"]
packages = ["hdx.api", "hdx.data", "hdx.facades"]

[tool.pydoc-markdown.renderer]
type = "mkdocs"
output_directory = "docs/build"

    [tool.pydoc-markdown.renderer.mkdocs_config]
    site_name = "HDX Python API"
    theme = "readthedocs"
    repo_url = "https://github.com/OCHA-DAP/hdx-python-api"

    [tool.pydoc-markdown.renderer.markdown.source_linker]
    type = "github"
    repo = "OCHA-DAP/hdx-python-api"

    [[tool.pydoc-markdown.renderer.pages]]
    title = "Home"
    name = "index"
    source ="docs/main.md"

    [[tool.pydoc-markdown.renderer.pages]]
    title = "API Documentation"

        [[tool.pydoc-markdown.renderer.pages.children]]
        title = "Configuration"
        contents = ["hdx.api.configuration.*"]

        [[tool.pydoc-markdown.renderer.pages.children]]
        title = "Locations"
        contents = ["hdx.api.locations.*"]
...

[NiklasRosenstein]

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

```py template "mkdocs" def api_pages = { "Configuration": "hdx.api.configuration", "Locations": "hdx.api.locations", # ... } action "preprocess-markdown" { use "pydoc" { loader().packages = api_pages.values() } } do name: "generate-api-pages" closure: { precedes "preprocess-markdown" } action: { for title, package in api_pages.items(): def filename = directory / 'content' / 'api' / (package + '.md') filename.parent.mkdir(parents=True, exist_ok=True) filename.write_text('---\ntitle: {}\n---\n@pydoc {}\n'.format(title, package)) } ```

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.

• The loader is a PythonLoader by default that is initialized with sensible default search paths
• The processors are currently hardcoded and no public API exists to modify them. It uses the same set of processors that the old-style configuration used if no processors were explicitly configured, except for a slight change to the cross-ref processor which must produce Novella {@link} tags
• The renderer is a MarkdownRenderer with some parameters changed by default
• It also tries to automatically detect an applicable source linker

https://github.com/NiklasRosenstein/pydoc-markdown/blob/02713da85cb77ab777fec122ab42e15fa6624ef4/src/pydoc_markdown/novella/preprocessor.py#L56-L76 https://github.com/NiklasRosenstein/pydoc-markdown/blob/02713da85cb77ab777fec122ab42e15fa6624ef4/src/pydoc_markdown/novella/preprocessor.py#L26-L42