Info about submodules is not being displayed as markdown

[nbro]

Look for example at this result:

even though inside the module the result is as expected

but it would be nice that the external part is also markdown, or it's better not to have that initial introduction at all. Is this bug?

[BurntSushi]

I don't see the problem. Module documentation is rendered as markdown. If the docs aren't formatted as markdown, then it won't render how you want.

It's pretty hard to say anything more without seeing the input.

[nbro]

@BurntSushi ands.algorithms.ode is just a folder with a __init__.py file, which contains just comments saying that it's required to consider the folder ode a Python package in the versions previously to Python 3.3.

That info, which is not displayed as markdown, is automatically displayed, I guess, by pdoc by gathering it from the module forward_euler.py. The docstrings in forward_euler.py are indeed markdown.

If you want to see the project: https://github.com/nbro/ands/tree/master/ands/algorithms/ode. I've also created a script (under the folder scripts of the root folder of the project) that uses pdoc to generate the documentation, if you want to use it.

[BurntSushi]

I don't understand what you expect to happen. pdoc can't magically turn a non-Markdown docstring into a Markdown string.

[nbro]

@BurntSushi Those strings are Markdown! The info that I'm claiming is displayed not in Markdown, that is:

are actually Markdown strings, as you can see from the source code (that I linked you to):

"""
# Meta info

Author: Nelson Brochado

Created: 10/09/2016

Updated: 19/02/2017

# Description

The forward Euler's method for solving ODEs is the easiest method
for approximately solving a _initial value_ ODE problem.
Hence it's used, in general, as a vehicle for studying
several important and basic notions on numerical ODE methods.

i.e., # Meta info and # Description should be displayed as titles, and this is indeed what happens in this comment:

Meta info

Author: Nelson Brochado

Created: 10/09/2016

Updated: 19/02/2017

Description

The forward Euler's method for solving ODEs is the easiest method
for approximately solving a initial value ODE problem.
Hence it's used, in general, as a vehicle for studying
several important and basic notions on numerical ODE methods.

[BurntSushi]

@nbro Interesting. Not sure what the problem is. I'd check the markdown template to see if there's anything fish with showing the docs for submodules.