It would be nice if Sphinx (reStructure Text) syntax could be converted sot that :meth:func_name``would be displayed as code. It must not necessarily link to the function, but it would be nice to have. Also, the:param name: text...and:raise ExceptionName: text.. etc. should be handled.

Also, some use this kind of syntax:

Args:
    filename (str): The filename ...
Returns:
    str: The new filename ...
Raises:
    TypeError: Foo ...

Hi,

I have an issue when disabling both add_method_class_prefix & add_member_class_prefix in the MarkdownRenderer, it breaks the TOC, that still looks for the fully qualified name (with the class prefix). Is this a known bug or a misconfiguration on my end?

Also is there a way to remove the prefix in the top module? (for instance in the screenshot instead of mtb.blender.mgl I want mgl)

Thanks

I'm running pydoc-markdown 3.1.1 with the following config:

loaders:
    - type: python
processors:
    - type: filter
    - type: smart
    - type: crossref
renderer:
    type: mkdocs
    site_name: Cape-Python-API
    content_directory_name: docs
    output_directory: ../pythonv1
    pages:
    - title: cape_privacy
      source: 'README.md'
    - title: cape_privacy.pandas
      contents:
      - cape_privacy.pandas._init_.py
      children:
      - title: pandas.registry
      contents:
      - cape_privacy.pandas.registry.py

There are no errors, and there is some output: I get all the files I'd expect:

The README content is correctly picked up and copied over. When I run mkdocs serve, it displays. The other pages exist, and can be reached via the menu, but they are blank.

I'm not totally sure how much of the code would be picked up - it's possible _init_.py doesn't have the right contents. But cape_privacy.pandas.registry.py definitely contains docstrings that I would expect to see (and they appear fine with other tools such as pdoc)

The following is one part of the registry.py file:

def get(transformation: str) -> TransformationCtor:
    """Returns the constructor for the given key.

    Arguments:
        transformation: The key of transformation to retrieve.
    """
    return _registry.get(transformation, None)

Any idea why nothing is showing up?

Hi,

I just installed the @develop version (because main release does not work with my project)

When I try to do a pydoc-markdown --modules debug --search-path src/ > docs.md (debug is my module), I got this error :

Traceback (most recent call last): File "/usr/local/bin/pydoc-markdown", line 6, in from pydoc_markdown.main import _entry_point File "/usr/local/lib/python3.7/site-packages/pydoc_markdown/main.py", line 30, in from nr.types import record ImportError: cannot import name 'record' from 'nr.types' (/usr/local/lib/python3.7/site-packages/nr/types/init.py)

I searched on nr.types : https://pypi.org/project/nr.types/ And I cannot find nr.types.record

I'm working with Python 3.7, is this the reason of this fail ?

Thanks !

command-line invocation fails with the error

pkg_resources.DistributionNotFound: The 'dataclasses<1.0.0,>=0.6.0' distribution was not found and is required by nr.parsing.date

this is in python=3.9.6, so dataclasses should be natively available. I've also tried explicitly installing several different versions of dataclasses using conda and pip with no effect.

Environment

• Pydoc-Markdown Version: v4.6.3
• Python Version: v3.10.2
• Operating System: Ubuntu 20.04.03 LTS (GitHub Actions)

Describe the bug

• working (pydoc-markdown-4.5.1 databind.core-1.5.1 mkdocs-material-8.2.3 pymdown-extensions-9.2)
• broken (pydoc-markdown-4.6.3 databind.core-1.5.2 mkdocs-material-8.2.6 pymdown-extensions-9.3)
• still broken (as above but replacing node.docstring => node.docstring.content)

There's an odd config warning in all runs.

 [WARNING - pydoc_markdown.main]: Unknown configuration options:
  - $ (ObjectType(pydoc_markdown.PydocMarkdown)) [pydoc-markdown.yml]
  - .renderer (UnionType(pydoc_markdown.interfaces.Renderer))
  - $ (ObjectType(pydoc_markdown.contrib.renderers.mkdocs.MkdocsRenderer))
  - .pages (ListType(ObjectType(pydoc_markdown.util.pages.Page), python_type=Pages))
  - .7 (ObjectType(pydoc_markdown.util.pages.Page))
  - .children (ListType(ObjectType(pydoc_markdown.util.pages.Page)))
  - .0 (ObjectType(pydoc_markdown.util.pages.Page))
  - .directory (UnknownType())

Traceback (most recent call last):
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/yapf/yapflib/pytree_utils.py", line 119, in ParseCodeToTree
    tree = parser_driver.parse_string(code, debug=False)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/lib2to3/pgen2/driver.py", line 103, in parse_string
    return self.parse_tokens(tokens, debug)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/lib2to3/pgen2/driver.py", line 71, in parse_tokens
    if p.addtoken(type, value, (prefix, start)):
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/lib2to3/pgen2/parse.py", line 162, in addtoken
    raise ParseError("bad input", type, value, context)
lib2to3.pgen2.parse.ParseError: bad input: type=16, value='*', context=(' ', (2, 27))

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/yapf/yapflib/pytree_utils.py", line 125, in ParseCodeToTree
    tree = parser_driver.parse_string(code, debug=False)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/lib2to3/pgen2/driver.py", line 103, in parse_string
    return self.parse_tokens(tokens, debug)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/lib2to3/pgen2/driver.py", line 71, in parse_tokens
    if p.addtoken(type, value, (prefix, start)):
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/lib2to3/pgen2/parse.py", line 162, in addtoken
    raise ParseError("bad input", type, value, context)
lib2to3.pgen2.parse.ParseError: bad input: type=16, value='*', context=(' ', (2, 27))

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/yapf/yapflib/yapf_api.py", line 183, in FormatCode
    tree = pytree_utils.ParseCodeToTree(unformatted_source)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/yapf/yapflib/pytree_utils.py", line 131, in ParseCodeToTree
    raise e
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/yapf/yapflib/pytree_utils.py", line 129, in ParseCodeToTree
    ast.parse(code)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/ast.py", line 50, in parse
    return compile(source, filename, mode, flags,
  File "<unknown>", line 2
    async def gather(cls, *fs, *, loop=None, timeout=None, total=None, **tqdm_kwargs): pass
                               ^
SyntaxError: invalid syntax

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/opt/hostedtoolcache/Python/3.10.2/x64/bin/pydoc-markdown", line 8, in <module>
    sys.exit(cli())
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/click/core.py", line 1128, in __call__
    return self.main(*args, **kwargs)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/click/core.py", line 1053, in main
    rv = self.invoke(ctx)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/click/core.py", line 1395, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/click/core.py", line 754, in invoke
    return __callback(*args, **kwargs)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/pydoc_markdown/main.py", line 344, in cli
    session.render(pydocmd)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/pydoc_markdown/main.py", line 138, in render
    config.render(modules)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/pydoc_markdown/__init__.py", line 179, in render
    self.renderer.render(modules)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/pydoc_markdown/contrib/renderers/mkdocs.py", line 168, in render
    item.page.render(filename, modules, self.markdown, self._context.directory)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/pydoc_markdown/util/pages.py", line 179, in render
    renderer.render_single_page(fp, self.filtered_modules(modules), self.title)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/pydoc_markdown/contrib/renderers/markdown.py", line 443, in render_single_page
    self._render_recursive(fp, 1, m)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/pydoc_markdown/contrib/renderers/markdown.py", line 368, in _render_recursive
    self._render_recursive(fp, level, member)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/pydoc_markdown/contrib/renderers/markdown.py", line 368, in _render_recursive
    self._render_recursive(fp, level, member)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/pydoc_markdown/contrib/renderers/markdown.py", line 365, in _render_recursive
    self._render_object(fp, level, obj)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/pydoc_markdown/contrib/renderers/markdown.py", line 350, in _render_object
    self._render_signature_block(fp, obj)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/pydoc_markdown/contrib/renderers/markdown.py", line 329, in _render_signature_block
    code = self._format_function_signature(obj, add_method_bar=self.signature_with_vertical_bar)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/pydoc_markdown/contrib/renderers/markdown.py", line 299, in _format_function_signature
    result = self._yapf_code(result + ': pass').rpartition(':')[0].strip()
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/pydoc_markdown/contrib/renderers/markdown.py", line 281, in _yapf_code
    return FormatCode(code, style_config=style)[0]
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/yapf/yapflib/yapf_api.py", line 186, in FormatCode
    raise errors.YapfError(errors.FormatErrorMsg(e))
yapf.yapflib.errors.YapfError: <unknown>:2:28: invalid syntax

not sure if related to #246

Hi,

I wanted a way to use a LAN server instead of localhost, but it does not seem easily doable with configurations only. I did not find lots of info on the matter on Hugo's forums but it seems others are having the same issue.

This PR almost works, by settings serverURL to 0.0.0.0 (outside localhost) & serverPort to 8080 (an open port on my router) I can access the doc from anywhere on the local network.

The only issue is that all the links are pointing to localhost... But replacing localhost with the machine's IP does work. I tried to set the IP as baseURL as advised in a Hugo issue but that did not work with pydoc markdown.

Tell me if there is an interest in making it part of the library.

From https://github.com/NiklasRosenstein/pydoc-markdown/pull/135#issuecomment-660022986

Make [view source] link

• [x] right-aligned
• [x] smaller font
• [ ] on the same visual line as the heading (https://stackoverflow.com/questions/13194692/align-h1-header-and-normal-text-in-same-line)

Even just the first two help, e.g.:

using style="float: right; font-size: 75%;" changes to:

Hi! I have a situation where everything is working locally, both with mkdocs serve and if I do mkdocs build then locally serve the results.

However, when I deploy to Netlify, I get 404s for all the pages generated by pydoc-markdown. A little digging showed that this is because a normal mkdocs.yml has the filepaths in the nav with / (e.g. myDir/myfile.md), but pydoc-markdown's autogenerated mkdocs.yml uses \ (e.g. myDir\myfile.md) It seems local mkdocs can handle this, but Netlify can't - it generates the following warnings:

11:04:26 AM: INFO    -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
11:04:26 AM:   - pythonv1/cape_privacy.pandas/dtypes.md

11:04:26 AM: WARNING -  A relative path to 'pythonv1/cape_privacy.pandas\dtypes.md' is included in the 'nav' configuration, which is not found in the documentation files

Manually editing the autogenerated mkdocs.yml to us / fixed this.

I suspect this isn't entirely an issue with pydoc-markdown (I am using a combination of pydoc-markdown, Spotify's Monorepo plugin, and then building and deploying with Netlify). So I understand if you don't feel this is something you need to fix. However I thought I'd raise it as it does seem like the mkdocs.yml you generate may be non-standard, and possibly this issue will help future users.

Versions: pydoc-markdown 3.1.1 python 3.7

~~Probably a Python3.9 issue.~~ From https://github.com/tqdm/tqdm/runs/2659177454:

$ pydoc-markdown --build --site-dir _site
Traceback (most recent call last):
  File "/opt/hostedtoolcache/Python/3.9.5/x64/bin/pydoc-markdown", line 8, in <module>
    sys.exit(cli())
  ...
  File "/opt/hostedtoolcache/Python/3.9.5/x64/lib/python3.9/site-packages/pydoc_markdown/contrib/loaders/python.py", line 114, in <listcomp>
    [x.name for x in discovered_items if x.is_module()],
AttributeError: '_Module' object has no attribute 'is_module'

Hi @NiklasRosenstein !

I want to address two issues we met with the renderer I implemented, and I think that other users of the renderer would meet this issues:

• shorten the label of the modules in the docusaurus sidebar, and use relative name instead fo full module name. Seems more natural and will avoid horizontal scrolls
• nest the documentation of a module's __init__.py file under the right folder (it wasn't the case, an error on my end)
• fix the rendering of the sidebar in case sidebar_top_level_label is null
• add a new option sidebar_top_level_module_label that controls the sidebar label of the top-level module (assuming there is only one)

I've implemented these using TDD. Let me know if that works for you 🙏

Hi, I stumbled upon this library while looking for a tool to add a Python API reference to our Docusaurus docs page. I read in the README that pydoc-markdown is switching to Novella for rendering, but Novella templates are only available for MkDocs and Hugo. What is the status of Docusaurus support at the moment? How difficult would it be to get pydoc-markdown to render my docs into Docusaurus? Thanks!

Environment

• Pydoc-Markdown Version: v4.6.4
• Python Version: v3.10.5
• Operating System: Ubuntu 22.04

Describe the bug

When using the MarkdownRenderer with add_full_prefix enabled, if there are functions defined in the __init__.py file, the prefix will also contain __init__.. Refer to https://github.com/NiklasRosenstein/pydoc-markdown/blob/3aa2fa94f514ee827992e4145a23e1260b5a4efd/src/pydoc_markdown/contrib/renderers/markdown.py#L47-L48

Expected behavior

I think __init__ should be ignored in the dotted_name function. Let's say you have a demo function in my_package/__init__.py, its title should be my_package.demo instead of my_package.__init__.demo.

Environment

• Pydoc-Markdown Version: 4.6.4
• Python Version: v3.7.15, v3.8.14 (pipelines for 3.9-3.11 haven't run yet but I suspect them to fail with the same as well)
• Operating System: ubuntu 20.04 (github actions ubuntu-latest image)

Describe the bug

Running the tool results in

File "/opt/hostedtoolcache/Python/3.7.15/x64/bin/pydoc-markdown", line 8, in <module>
    sys.exit(cli())
  File "/opt/hostedtoolcache/Python/3.7.15/x64/lib/python3.7/site-packages/click/core.py", line 1[13](https://github.com/priv-kweihmann/oelint-parser/actions/runs/3464057845/jobs/5785117241#step:8:14)0, in __call__
    return self.main(*args, **kwargs)
  File "/opt/hostedtoolcache/Python/3.7.15/x64/lib/python3.7/site-packages/click/core.py", line 1055, in main
    rv = self.invoke(ctx)
  File "/opt/hostedtoolcache/Python/3.7.15/x64/lib/python3.7/site-packages/click/core.py", line [14](https://github.com/priv-kweihmann/oelint-parser/actions/runs/3464057845/jobs/5785117241#step:8:15)04, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/opt/hostedtoolcache/Python/3.7.[15](https://github.com/priv-kweihmann/oelint-parser/actions/runs/3464057845/jobs/5785117241#step:8:16)/x64/lib/python3.7/site-packages/click/core.py", line 760, in invoke
    return __callback(*args, **kwargs)
  File "/opt/hostedtoolcache/Python/3.7.15/x64/lib/python3.7/site-packages/pydoc_markdown/main.py", line 370, in cli
    pydocmd = session.load()
  File "/opt/hostedtoolcache/Python/3.7.15/x64/lib/python3.7/site-packages/pydoc_markdown/main.py", line 1[16](https://github.com/priv-kweihmann/oelint-parser/actions/runs/3464057845/jobs/5785117241#step:8:17), in load
    config.load_config(self.config)
  File "/opt/hostedtoolcache/Python/3.7.15/x64/lib/python3.7/site-packages/pydoc_markdown/__init__.py", line 113, in load_config
    result = databind.json.new_mapper().deserialize(data, type(self), filename=filename, settings=[unknown_keys()])  # type: ignore[arg-type]  # noqa: E501  # Bad databind typehint
  File "/opt/hostedtoolcache/Python/3.7.15/x64/lib/python3.7/site-packages/databind/core/mapper/objectmapper.py", line 94, in deserialize
    return self.convert(Direction.deserialize, value, type_hint, filename, pos, key, annotations, settings)
  File "/opt/hostedtoolcache/Python/3.7.15/x64/lib/python3.7/site-packages/databind/core/mapper/objectmapper.py", line 83, in convert
    return ctx.convert()
  File "/opt/hostedtoolcache/Python/3.7.15/x64/lib/python3.7/site-packages/databind/core/mapper/converter.py", line 1[19](https://github.com/priv-kweihmann/oelint-parser/actions/runs/3464057845/jobs/5785117241#step:8:20), in convert
    return converter.convert(self)
  File "/opt/hostedtoolcache/Python/3.7.15/x64/lib/python3.7/site-packages/databind/json/modules/object.py", line 112, in convert
    return self._deserialize(ctx, ctx.type)
  File "/opt/hostedtoolcache/Python/3.7.15/x64/lib/python3.7/site-packages/databind/json/modules/object.py", line 72, in _deserialize
    ctx.push(flat_field.field.type, value, name, flat_field.field).convert()
  File "/opt/hostedtoolcache/Python/3.7.15/x64/lib/python3.7/site-packages/databind/core/mapper/converter.py", line 119, in convert
    return converter.convert(self)
  File "/opt/hostedtoolcache/Python/3.7.15/x64/lib/python3.7/site-packages/databind/json/modules/union.py", line 64, in convert
    result = child_context.convert()
  File "/opt/hostedtoolcache/Python/3.7.15/x64/lib/python3.7/site-packages/databind/core/mapper/converter.py", line 119, in convert
    return converter.convert(self)
  File "/opt/hostedtoolcache/Python/3.7.15/x64/lib/python3.7/site-packages/databind/json/modules/object.py", line 112, in convert
    return self._deserialize(ctx, ctx.type)
  File "/opt/hostedtoolcache/Python/3.7.15/x64/lib/python3.7/site-packages/databind/json/modules/object.py", line 72, in _deserialize
    ctx.push(flat_field.field.type, value, name, flat_field.field).convert()
  File "/opt/hostedtoolcache/Python/3.7.15/x64/lib/python3.7/site-packages/databind/core/mapper/converter.py", line 119, in convert
    return converter.convert(self)
  File "/opt/hostedtoolcache/Python/3.7.15/x64/lib/python3.7/site-packages/databind/json/modules/collection.py", line [29](https://github.com/priv-kweihmann/oelint-parser/actions/runs/3464057845/jobs/5785117241#step:8:30), in convert
    for idx, val in enumerate(ctx.value))
  File "/opt/hostedtoolcache/Python/3.7.15/x64/lib/python3.7/site-packages/databind/json/modules/collection.py", line 29, in <genexpr>
    for idx, val in enumerate(ctx.value))
  File "/opt/hostedtoolcache/Python/3.7.15/x64/lib/python3.7/site-packages/databind/core/mapper/converter.py", line 116, in convert
    raise ConverterNotFound(self.type, self.direction)
databind.core.mapper.converter.ConverterNotFound: (ConcreteType(pydoc_markdown.util.pages.Page), <Direction.deserialize: 1>)

only difference between the latest good run and the failing is

exceptiongroup-1.0.1 > exceptiongroup-1.0.2 pydoc-markdown-4.6.3 > pydoc-markdown-4.6.4

Expected behavior

No exception, as the point release before worked fine

Environment

• Pydoc-Markdown Version: 4.6.3
• Python Version: v3.9.14
• Operating System: Ubuntu

Describe the bug

Following the getting started guide I get :

❯ novella
Created temporary build directory /tmp/novella-u5rsn3nx
Copy ['content'] to /tmp/novella-u5rsn3nx
Watch /home/arthur/src/client/org/project/docs/content
Detected Git repository URL: https://github.com/org/project
Detected edit URI: blob/develop/docs/content
Generating new /tmp/novella-u5rsn3nx/mkdocs.yml
Discovered Python modules ['conf'] and packages ['tests', 'cmdb_pic_tooling'] in '/home/arthur/src/client/org/project/docs/..'.
Load Python modules (search_path: ['/home/arthur/src/client/org/project/docs/../src', '/home/arthur/src/client/org/project/docs/..'], modules: ['conf'], packages: ['cmdb_pic_tooling'], discover: True)
Watch /home/arthur/src/client/org/project/README.md
Run $ mkdocs build -d /home/arthur/src/client/org/project/docs/_site
ERROR   -  Config value: 'theme'. Error: Unrecognised theme name: 'material'. The available installed themes are: mkdocs, readthedocs 
ERROR   -  Config value: 'markdown_extensions'. Error: Failed loading extension "pymdownx.betterem". 

Aborted with 2 Configuration Errors!
Error: Failed loading extension "pymdownx.betterem". defined at /home/arthur/.local/pipx/venvs/novella/lib/python3.10/site-packages/novella/templates/mkdocs.py:102
Traceback (most recent call last):
  File "/home/arthur/.local/pipx/venvs/novella/lib/python3.10/site-packages/novella/build.py", line 152, in _run_actions
    action.execute(self)
  File "/home/arthur/.local/pipx/venvs/novella/lib/python3.10/site-packages/novella/action.py", line 151, in execute
    raise RuntimeError(f'command exited with code {self._proc.returncode}')
RuntimeError: command exited with code 1

Expected behavior

For it to generate some docs ?

Is your feature request related to a problem? Please describe.

I expect I am not the only user of pydoc-markdown who is using 4.5.1 before the major changes that came with 4.6.0 (which seem like such a big change that perhaps it should be 5.x.x?). The problem is the documentation for 4.5.1 is no longer available on readthedocs.

Describe the solution you'd like

Make the documentation for 4.5.1 available again (eg. on readthedocs with a notice that documentation for 4.6.0 and later is on github.io or as versioned documentation on readthedocs or on a GitHub branch).

Describe alternatives you've considered

I can get to the old README using the GitHub tag and the md files used to generate the documentation.

Additional context

Another possibility to consider is to keep 4.5.1 in a separate repo since 4.6.0+ is really a complete rewrite with what appear to be different aims rather than an incremental development.