Way to add external Markdown file

[kidpixo]

first of all, thanks, pdoc is amazing!

Problem Description

I have a CHANGELOG.md file that doesn't fit to any particular function documentation. I want to create an extra page in the main index listing to show this file. Any Idea?

Proposal

No concrete ideas, maybe we can add the markdown files in the tree and add them as a "fake module" at that level?

Alternatives

Additional context

I'm documenting several packages, because this is only one project. I extended the default template index to have a generic landing page. I also changed the modules listing to make the top level bold (code here below, maybe useful to other).

Project structure :

project/
├── CHANGELOG.md
├── README.md
├── package2/
├── package2/
└─── doc
    ├── MERTIS.png
    ├── custom-template
    │   ├── index.html.jinja2
    │   └── module.html.jinja2
    ├── index.html
    ├── package
    ├── package.html
    ├── search.js
    ├── package2
    └── package2.html

Extra

this is my index.html.jinja2 , this overwrites the nav block entirely.

{% block nav %}
    <h2>Available Modules</h2>
    <ul>
        {% for submodule in all_modules if "._" not in submodule and not submodule.startswith("_") %}
            <li><a href="{{ submodule.replace(".","/") }}.html">
            {% if  "." not in submodule %}
                <span style="font-weight:bold">{{ submodule }} (top level)</span>
            {% else %}
                {{ submodule }}
            {% endif %}
            </a></li>
        {% endfor %}
    </ul>
{% endblock %}

[mhils]

I have a CHANGELOG.md file that doesn't fit to any particular function documentation. I want to create an extra page in the main index listing to show this file. Any Idea?

I'd just link to GitHub/... for the changelog. Alternatively, you can create a CHANGELOG.py file and include that in your pdoc invocation (pdoc your_module ./CHANGELOG.py). That feels a bit messy, but may be what you are after.

[kidpixo]

Thanks for the answer @mhils. Your way is nice, but my project is not on github, and probably will never be (internal gitlab at work, internal bitbucket at ESA etc). The "fake" CHANGELOG.py approach hit me too, I didn't know I can include a file like this, I'll give it a try.

[kidpixo]

@mhils thanks, this works.

I found a strange quirk :

Using pdoc ./CHANGELOG.py module1 module2 only CHANGELOG (the first listed) is properly rendered, the other modules only get the top level documentation from the respective __init__.py with no structure of all the modules functions.

Using I do pdoc module1 module2 ./CHANGELOG.py (listed last ) everything is fine and module1 and module2 are being fully documented with all functions, bells & whistles.

Maybe pdoc stops scanning the other directories because the first "module" is a file? just randomly guessing.

[mhils]

Hard to say in general what's going on, you can probably figure out more with print statements in https://pdoc.dev/docs/pdoc/extract.html#walk_specs. One potential source of issues here could be that the CHANGELOG.py directory is added to sys.path and that somehow screws up things.

[kidpixo]

thanks @mhils I'll look into it, but the current behavior is good enough for me.

[kidpixo]

another information : pdoc module1 ./CHANGELOG.py module2 results in module1 correctly parsed and documented, module2 has only a sidebar entry, that point to empty content.

module2.html is created, but it seems pdoc doesn't parse module2 content.

[kidpixo]

for future reference : maybe the easiest way is to run something like this

sed -i '/## Changelog/r CHANGELOG.md' doc/custom-template/index.html.jinja2

I'm using a makefile in the base directory, this way I can simply add this line before the doc creation target.

taking care that your index.html.jinja2 have a ## Changelog in it, this will add the whole file to the rendered index page.

My project basic structure is :

project directory/ < directory, NOT a python module (no __init__.py)
├ module1/         < directory, python module
├ module2/         < directory, python module
├ Makefile
├ CHANGELOG.md     < Markdown file I want to include in doc
└ CHANGELOG.py     < python file that only includes CHANGELOG.md via sphinx directives