Goals: add markdown as output format because readthedocs has support only for rst and md formats right now.

• add cli options: --markdown, --walk-path, --walk-path-followlinks
• change cli option --html-dir to --output-dir
• add md.mako template based on text.mako
• you can now specify many modules per one executing
• walk-path option allows recursively find all modules in path via init.py file, '.py' extension and even via 'python' word in the shebang

I am very happy to find pdoc! I looked at other choices and they were heavy and poorly documented. So excellent to find something that works right away and is easy to manipulate.

That said, I have spent a few hours with the code but haven't quite figured out how to restrict the scope of documentation to just the contents of the module. I want to be able to only document:

• module scope variables
• module scope functions
• classes in a module
• methods in a class in a module
• instance variables in a class in a module

A standard use case for this that I imagine isn't just mine is for unit tests. Including in the documentation all the methods inherited from UnitTest does not add useful information.

I think this applies generally for any situation where you want the documentation to only focus on the module source, rather than being comprehensive about all the context of that module. In my case, I am documenting an intentionally minimal library and a very strong design goal is keeping every aspect of it as brief and simple as possible.

I will happily provide a pull request if necessary to implement this.

Thanks!

I have one related question about the html output after running the above script.

# script full path: C:\Dropbox\python\create_pdoc.py
import pdoc
from pathlib import Path
myscripts = ["./myscript.py", "./path2/myscript.py", "./myscript3.py"]
pdoc.pdoc(*myscripts, output_directory=Path("./_mydocs"))

I run this script calling C:\python38\python C:\Dropbox\python\create_pdoc.py The .py scripts to be documented are in the same C:\Dropbox\python\ folder (or children folders, like the script inside path2 subfolder). I don't think their content is relevant for this question (they just contain a sample function definition followed by a docstring comment: """ my comments """).

As expected, the output (3 html documents + index.html + search.js) is created in C:\Dropbox\python\_mydocs And index.html left menu shows links to the other 3 html docs in same order as they are in myscripts list, like this:

Available Modules

• Dropbox.python.myscript
• myscript
• Dropbox.python.myscript3

What I don't understand is the reason why the 2nd one (located inside path2) shows no path information, while the 1st and 3rd (located in the same folder as my create_pdoc.py script) show the full path below C: (i.e. Dropbox.python.)

How can I control that? I would have expected one of these results instead:

Available Modules

• myscript
• path2.myscript
• myscript3

Available Modules

• Dropbox.python.myscript
• Dropbox.python.path2.myscript
• Dropbox.python.myscript3

... either all or none scripts preceded by Dropbox.python. path (although I would prefer not to show it)

Originally posted by @abubelinha in https://github.com/mitmproxy/pdoc/issues/322#issuecomment-1003104131

This question was closed in the past, but the solution didn't solve it for me. I'm running Windows 7 and python 2.7

I'm installing pdoc globally using "pip install pdoc". It says that it pip installs correctly, puts a file called 'pdoc' (no extension) into my Python27/Scripts (which is on my PATH), however when I type "pdoc" in the command line I get the following... 'pdoc' is not recognized as an internal or external command, operable program or batch file'

The previous closed issue was solved by running "pip install --system pdoc" but that was for Ubuntu and doesn't seem to be an option for Windows.

Problem Description

When browsing documentation, the source code details are hidden and docstring appears in its natural place, right below the function definition ... until you click the "view source" option. After clicking that option, source code appears between function definition and docstring ... so docstring gets displaced down many lines (as many as the code length). So all the rich docstring format and all links it might contain disappear from our scope (until we close the source code).

1. Default view:

<div class="attr function">...</div>     <details> <summary>View Source</summary>
<div class="codehilite"></div></details>   <---- HIDDEN STUFF
<div class="docstring">...</div>   <----   possible links to other modules and functions

2. Click "view source"

<div class="attr function">...</div>     <details> <summary>View Source</summary>
    <div class="codehilite">
    ...
    ...
    ...
    ...
    ...
    ...
    ...
    ...
    ...
    ...
    </div>
</details>
<div class="docstring">...</div>   <----   Hey!!!  I was at top but I am here now. Move up & down to read me if you want.

Proposal

In my opinion, it might be much better to keep docstring below function definition, and put source code below docstring. So we can still see the nice docstring in its original place, and use the links to other functions and modules without having to move down.

<div class="attr function">...</div>
<div class="docstring">...</div>   <----   Don't worry. I am still here and will always be.
<details>
    <summary>View Source</summary>
    <div class="codehilite">
    ...
    ...
    ...
    ...
    ...
    ...
    ...
    ...
    ...
    ...
    </div>
</details>

Alternatives

Can I configure this using templates? Anyway, I think the default look would improve with this change.

Google docstrings are increasingly common. There are definitely other users who use Google-style strings as well.

I've implemented some very basic parsing for Google-style docstrings in html-google.mako. Seems like a project like this could benefit from natively supporting a few common docstring styles, so I'd be willing to generalize this to numpy-style as well and add a flag --style=google perhaps.

Looking forward to hearing your thoughts! cc @BurntSushi for discussion as to if we should merge, cc @igordertigor because I thought you might be interested in seeing this.

Google Style

"""
A short description of the function goes here.

Arguments:
    argname (type): Description.
    secondarg (type : default): Description.

Returns:
    boolean: True on success.
"""

Problem Description

As a Python newbie, my functions contain not only documentation strings below function definition. I also use to insert some tips (# _TIP marks) about how-to-do something in Python, the first time I use that kind of code.

# file myscript_A.py
def myfunction1():
    """ my documentation """
    mylist = ["Jane", "John", "Jennifer"]
    surname = "Johanssen"
    # _TIP: list comprehension
    fullnames = [name+" "+surname for name in mylist]
...
def myfunction5():
    """ my documentation """
    import pandas as pd
    # _TIP: pandas dataframe merging
    pd.read_csv(...)

# file myscript_B.py
def myfunction22():
    """ my documentation """
    # my code
    # my code
    # _TIP: whatever
    # my code
    # my code
...

Proposal

I have created a tips_collector.py script, which reads a list of given python scripts content, locates all lines containing "# _TIP" marks, and generates a my_tips.html file like this:

• myscript_A.py [line 6]: list comprehension
• myscript_A.py [line 165]: pandas dataframe merging
• myscript_B.py [line 87]: whatever

As I have the line numbers and I also have pdoc-generated html documentation for each of these scripts, I would like to improve my_tips.html file including links to open documentation of container function for each of those tips. I would take profit of anchor marks generated by pdoc (i.e. <a href=./myscript_A.html#myfunction1>list comprehension</a>), like this:

• myscript_A.py [line 6]: list comprehension
• myscript_A.py [line 165]: pandas dataframe merging
• myscript_B.py [line 87]: whatever

Obviously, to do this I need a way to get the function name which contains a given line of code inside a given script file. So get_function_name("myscript_A.py", 165) should return "myfunction5":

def get_function_name(script_name, line_number):
    # what should I do here?
    return(function_name)

Alternatives

I think these issues and concepts are somehow related, but I would need some examples so I can connect them to my specific problem: #268 Get line number of classes and functions Doc.source_lines

Additional context

I am generating my pdoc html documents using the approach described in #325

I am trying to create a html documentation for a module with the following command:

pdoc --html --overwrite huffman.py 

But I am receiving the following error:

Traceback (most recent call last):
  File "/Library/Frameworks/Python.framework/Versions/3.5/bin/pdoc", line 458, in <module>
    module = imp.load_source('__pdoc_file_module__', fp, f)
  File "/Library/Frameworks/Python.framework/Versions/3.5/lib/python3.5/imp.py", line 172, in load_source
    module = _load(spec)
  File "<frozen importlib._bootstrap>", line 693, in _load
  File "<frozen importlib._bootstrap>", line 673, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 662, in exec_module
  File "<frozen importlib._bootstrap>", line 222, in _call_with_frames_removed
  File "/Users/cell/Desktop/ands/algorithms/greedy/huffman.py", line 56, in <module>
    from ...ds.MinPriorityQueue import *
SystemError: Parent module '' not loaded, cannot perform relative import    

I know that the problem is related to the fact that I am doing a relative import, which doesn't work because huffman.py is not being imported as I programmed it to be imported. So, currently, I am using the following code:

if __name__ == "__main__":
    from os import path, sys
    BASE_DIR = path.dirname(path.dirname(path.dirname(__file__)))  # ands
    sys.path.append(BASE_DIR)
    from ds.MinPriorityQueue import *
else:
        from ...ds.MinPriorityQueue import *

Which is already a mess, because I am trying to handle both when this huffman.py file (or module) is run as main or imported from outside ands, which is the parent of the parent of the package where huffman.py is situated. To solve the problem, I did the following:

from os import path, sys
BASE_DIR = path.dirname(path.dirname(path.dirname(__file__)))  # ands
sys.path.append(BASE_DIR)

if __name__ == "__main__":
    from ds.MinPriorityQueue import *
else:
    try:
        from ...ds.MinPriorityQueue import *
    except SystemError:
        from ds.MinPriorityQueue import *

Unfortunately this is far from being simple, considered that what I want to achieve should be very simple.

Any suggestions to simplify my code?

I try using pdoc for a basic python project using the "src layout", like

.
├── pyproject.toml
├── README.md
├── setup.py
├── src
│   ├── dep.py
│   ├── main.py
└── tests
    └── test_dep.py

environment:

pdoc: 12.0.2
Python: 3.8.10
Platform: Linux-5.15.0-41-generic-x86_64-with-glibc2.29

setup.py:

setup(
...
packages=find_packages(where='./src'),
package_dir={'': 'src'},

...

Now i want to generate documentation for the modules in the src directory. From the root of the project i execute the following command:

pdoc --docformat markdown --output-directory docs/ src/

However, this lists the modules src.main and src.dep. This is not correct, src is not a package, but the root dir for the source files ("src layout" paradigm). Note: removing the top level help does not help either.

If executing

cd src
pdoc --docformat markdown --output-directory ../docs/ *.py

the expected module names appear in the generated documentation. However, i have no possibility to include top level documentation, because the init.py is gone and afaik it is needed for this.

Is this the correct way to deal with pdoc in this use case or am i missing something?

Problem Description

Natively since Python 3.9, but using from __future__ import annotations on some version prior you can use syntax like str | int instead of Union[str, int]. This is supported by type parsers and python alike, but pdoc seems to not like it that much. While the website builds to a certain point, it doesn't complete the full generation.

Steps to reproduce the behavior:

1. Parse code with type unions using the pipe operand
2. ???
3. Profit

System Information

pdoc: 8.1.0
Python: 3.9.9
Platform: macOS-12.0.1-arm64-arm-64bit

Problem Description

Currently when generating via pdoc, the index.html creates a "module" index with no content, other then a search bar. When using the documentation, all pages also contain a relative link to this module index, making it inevitable to be seen by customers.

Proposal

I would like to be able to configure the logo, and default content. Ideally specify one module and render that modules description. Ofc this has the additional problem of duplicating documentation - so not sure how to approach this best.

Problem Description

I would like to .. include:: ../README.rst in my __init__.py module docstring. However, it appears to be parsed as markdown, despite the fact that it has the appropriate file extension and my docstring format is set to rst (i.e. left as default). Is this a missing feature, or am I doing something wrong?

__init__.py

"""
.. include:: ../README.rst
"""

README.rst

...
A :ref:`Task` is connected to repositories through **:ref:`links <Link>`**. A link is a repository plus a collection of properties describing the repository's relationship to the task - i.e. whether it is input or output, whether it should inhibit dependent tasks from starting, etc.
...

rendered

System Information

pdoc: 12.3.0
Python: 3.10.6
Platform: Linux-5.17.0-1021-oem-x86_64-with-glibc2.35

Problem Description

Currently, pdoc only supports one version of a given Python package.

Proposal

I would like to see (optional) support for multiple versions of a package in pdoc. It's possible that some users of a package do not use the version whose current documentation is available, and having the option to switch versions would greatly aid in usability, especially if some objects were removed/renamed between different package versions.

Alternatives

I think Sphinx has support for this feature, but I have not tested it.

Additional context

None.

Problem Description

I've got some Python 2.7 stuff in my project and while they function fine in the intended environment (Maya), pdoc can't execute them under 3.9 and I can't generate docs for any of the package despite just one file being problematic and hundreds being fine.

Proposal

A way to flag files as ignore completely, so we don't run into errors in "pdoc\extract.py", line 211, in load_module"

Alternatives

I've no idea sadly :(

Problem Description

This is not a bug per se, but I'm not sure what the "recommended" way to resolve the situation is. Basically, there is a slight problem when one wants to use the lru_cache decorator from the functools module on instance methods (described in more detail here), in that one should not do this:

class ExpensiveComputation:
    def __init__(self, ...):

    @lru_cache(maxsize=None)
    def calculate(self, ...):
        ...

but rather, something like this:

class ExpensiveComputation:
    def __init__(self, ...):
        ...
        self.calculate = lru_cache(maxsize=None)(self._calculate)

    def _calculate(self, ...):
        ...

The problem with the above is that pdoc does not document methods that begin with underscores, meaning there are at least 3 not-so-great ways to document the calculate method in the fixed version from above:

1. leave the docstring where it is; this means that the method is not documented at all (probably not the best)
2. rename _calculate to something that doesn't begin with an underscore and write a warning in the docstring to call calculate instead; this is a bit strange to both end users and myself
3. move the whole docstring to self.calculate (the now-member); the downsides of this are a) the full signature of the function is lost and needs to be documented, b) there is no "View Source" next to the method (since pdoc considers it a member), and c) it feels a bit strange to have such an enormous docstring in the middle of the constructor

So far, option 3 looks like the most sane one, but none of them are really "nice" (admittedly, the whole workaround for lru_cache is also a bit inelegant).

Steps to reproduce the behavior:

First (wrong) implementation:

import time
from functools import lru_cache


class ExpensiveComputation:
    def __init__(self, delay: int = 1):
        """
        Constructor

        Parameters
        ----------
        delay, optional
            the delay
        """
        self.delay = delay

    @lru_cache(maxsize=None)
    def calculate(self, arg: float) -> float:
        """
        Function for calculation

        Parameters
        ----------
        arg
            the parameter to square

        Returns
        -------
        float
            the result
        """
        time.sleep(self.delay)
        return arg**2

Rendering:

Second (fixed) implementation, with docstring fix from option 3:

import time
from functools import lru_cache


class ExpensiveComputation:
    def __init__(self, delay: int = 1):
        """
        Constructor

        Parameters
        ----------
        delay, optional
            the delay
        """

        self.delay = delay
        self.calculate = lru_cache(maxsize=None)(self._calculate)
        """
        Function for calculation

        Parameters
        ----------
        arg
            the parameter to square

        Returns
        -------
        float
            the result
        """

    def _calculate(self, arg: float) -> float:
        """
        Function for calculation

        Parameters
        ----------
        arg
            the parameter to square

        Returns
        -------
        float
            the result
        """
        time.sleep(self.delay)
        return arg**2

Rendering:

I've generated the above using the --docformat numpy flag, but it's not necessary to reproduce the behavior.

System Information

pdoc: 12.3.0
Python: 3.9.13
Platform: Linux-5.16.0-1-amd64-x86_64-with-glibc2.35

The Google list sections recognises currently only "Args", "Raises" and "Attributes" as headers for sections that consist of a definition list. This could be extended to recognise more section headers, similar to what sphinx already does.

The list of sections that sphinx supports is quite extensive, but I'd suggest at least adopting "Keyword Args", "Keyword Arguments", "Yields" and "Examples". The "Yields" header is specifically mentioned by Google as an alternative to "Returns", and I have seen "Examples" mentioned in older versions of the style guide. The keyword arguments are not specified by Google as such, but are widely used.

There are also other list-type sections on the Sphinx list, so implementing as much as possible would improve Sphinx compatibility a lot.

We have to deal with C# dlls and have some wrapper objects around those.

When run with pdoc we'd like to mock these objects to get descriptive documentation.

Is there a some environment variable or anything set by pdoc that would give us this information, e.g. like if TYPE_CHECKING.

Currently we are catching import errors and replacing it with mocks, which gives us nice documentation, but in case a dll is missing we loose valuable tracebacks.

Thanks a lot for maintaining this lovely piece of code. 😸