API Documentation for Python Projects

Overview

pdoc

pdoc documentation CI Status Code Coverage PyPI Version Supported Python Versions

API Documentation for Python Projects.

Example

pdoc -o ./html pdoc generates this website: pdoc.dev/docs.

Installation

pip install pdoc

pdoc is compatible with Python 3.8 and newer.

Usage

pdoc your_python_module
# or
pdoc ./my_project.py

Run pdoc pdoc to see pdoc's own documentation, run pdoc --help to view the command line flags, or check our hosted copy of the documentation.

Features

pdoc's main feature is a focus on simplicity: pdoc aims to do one thing and do it well.

  • Documentation is plain Markdown. There are no added special syntax rules.
  • First-class support for type annotations and all other modern Python 3 features.
  • Builtin web server with live reloading.
  • Customizable HTML templates.
  • Understands numpydoc and Google-style docstrings.
  • Standalone JS-free HTML output without additional dependencies.

Under the hood...

  • pdoc will automatically link identifiers in your docstrings to their corresponding documentation.
  • pdoc respects your __all__ variable when present.
  • pdoc will traverse the abstract syntax tree to extract type annotations and docstrings from constructors as well.
  • pdoc will automatically try to resolve type annotation string literals as forward references.
  • pdoc will use inheritance to resolve type annotations and docstrings for class members.

If you have substantially more complex documentation needs, we recommend using Sphinx!

Contributing

As an open source project, pdoc welcomes contributions of all forms.

Dev Guide

Also, please feel free to join our developer Slack!

Slack Developer Chat

pdoc vs. pdoc3

This project is not associated with "pdoc3", which often falsely assumes our name. Quoting @BurntSushi, the original author of pdoc:

I'm pretty disgusted that someone has taken a project I built, relicensed it, attempted to erase its entry on the Python Wiki, released it under effectively the same name and, worst of all, associated it with Nazi symbols.

Source: https://github.com/pdoc3/pdoc/issues/64

In contrast, the pdoc project strives to uphold a healthy community where everyone is treated with respect. Everyone is welcome to contribute as long as they adhere to basic civility. We expressly distance ourselves from the use of Nazi symbols and ideology.


The pdoc project was originally created by Andrew Gallant and is currently maintained by Maximilian Hils.

Issues
  • support for markdown output

    support for markdown output

    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
    opened by Friz-zy 30
  • Can I only document the module itself?

    Can I only document the module itself?

    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!

    opened by marksweiss 18
  • Inconsistent module names when specifying multiple paths

    Inconsistent module names when specifying multiple paths

    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

    bug 
    opened by mhils 17
  • Unable to run pdoc from command line

    Unable to run pdoc from command line

    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.

    opened by CadBrad 17
  • put source code below docstring

    put source code below docstring

    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
    
    1. 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.

    enhancement 
    opened by abubelinha 15
  • Add support for Google Style

    Add support for Google Style

    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.
    """
    
    opened by j6k4m8 15
  • link to a function inside a file (get function's name) when I only know a line number inside that file

    link to a function inside a file (get function's name) when I only know a line number inside that file

    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:

    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

    enhancement 
    opened by abubelinha 14
  • SystemError: Parent module '' not loaded, cannot perform relative import

    SystemError: Parent module '' not loaded, cannot perform relative import

    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?

    opened by nbro 14
  • Generate documentaton for python project with

    Generate documentaton for python project with "src layout"

    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?

    bug 
    opened by rmuller 13
  • Pipe operand for type unions causes type annotation errors

    Pipe operand for type unions causes type annotation errors

    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
    
    bug 
    opened by bczsalba 13
  • Configure module index

    Configure module index

    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.

    enhancement 
    opened by Fohlen 13
  • Types with nested

    Types with nested "|" (Union) are not formatted well

    For this program:

    from __future__ import annotations
    from typing import Iterable
    
    def function1(value: int | str = 1) -> None:
      pass
    
    def function2(value: int | str | Iterable[int | str] = 1) -> None:
      pass
    

    pdoc produces the documentation:

    def function1(value: int | str = 1) -> None:
    
    def function2(value: Union[int, str, Iterable[int | str]] = 1) -> None:
    

    If feasible, it might be best to always use the more modern ... | ... syntax and never the Union[...] syntax.

    bug 
    opened by hhoppe 4
  • Documentation: fix #422.

    Documentation: fix #422.

    This adds a single docstring to pdoc.doc.Class.own_members in order to make the behavior regarding __init__ methods on abstract classes more clear to users.

    I believe the docstring should be concise enough, but I did use a note admonition, which is not used anywhere else in the documentation that I know of, so if the style/formatting needs to be changed, please let me know!

    opened by GrammAcc 0
  • Update documentation of pdoc.doc.Class with info about __init__ on abstract base classes.

    Update documentation of pdoc.doc.Class with info about __init__ on abstract base classes.

    Problem Description

    I apologize if this is not the right template to use. I wasn't sure if I should use the bug report or proposal, but bug report seemed closer.

    I am working on a python project that will be packaged as a library, and I am using numpy style docstrings with the constructor documented in the class docstring, so I do not have a docstring on the __init__ method of my classes, and I am extending the default template to condense the constructor and class declaration into a single signature that reflects usage, but currently, the pdoc.doc.Class implementation of own_members explicitly removes __init__ from the returned list when the class is an abstract base class (see #273).

    The comment in the source code: https://github.com/mitmproxy/pdoc/blob/d444b885126fbce432bc168fae1cbaa041bda767/pdoc/doc.py#L652 as well as the issue referenced above make it clear that this is intended behavior, and this is easy to work around by adding a docstring to the __init__ method of the abstract classes that define a constructor as part of their API. However, this workaround is not clearly documented, and the code block that removes the __init__ method is in the Class._member_objects non-public method, which is called indirectly via Class.own_members > Namespace._members_by_origin > Namespace.members, which takes some poking around the source code to identify.

    Since this is expected behavior, but it can produce unexpected results in this particular edge case, I think the documentation should be updated to indicate this more prominently.

    I think adding this info to the docstring of pdoc.doc.Class.own_members would work since that's the portion of the public API that will likely be called when this problem arises.

    Steps to reproduce the behavior:

    1. clone the minimal repro: git clone https://github.com/GrammAcc/pdoc-init-abstractclass-repro.git
    2. cd into the local repo: cd pdoc-init-abstractclass-repro
    3. install pdoc into the local repo: pip install pdoc
    4. run pdoc with the custom template and class_signatures module: pdoc -t . class_signatures.py

    The webserver should open up the documentation page showing two class signatures. The expected output based on the custom template is for both signatures to show both arg1 and arg2, but the one for the class NoInitDocstring shows no arguments as if it did not have an __init__ method defined. After reviewing the source code and searching for issues on github, its clear that this behavior is intended, but it should be more clearly documented.

    System Information

    Paste the output of "pdoc --version" here. pdoc: 12.0.2 Python: 3.10.5 Platform: Linux-5.18.9-arch1-1-x86_64-with-glibc2.35

    enhancement 
    opened by GrammAcc 2
  • rendering of markdown gives bad result

    rendering of markdown gives bad result

    Problem Description

    rendering of markdown gives bad result if it contains headings, a fenced code block and some specific html

    Steps to reproduce the behavior:

    test script: markdown_test.py

    """
    # markdown test
    ## subsection 1
    
    ```
    fenced code block without syntax highlighting
    ```
    
    ## subsection 2
    
    ```python
    # fenced code block with syntax highlighting
    print("hello")
    ```
    
    ## subsection 3
    
    <h2> an html heading </h2>
    
    ## subsection 4 with an html table
    
    <ul>
        <li> one </li>
        <li> two </li>
        <li> three </li>
    </ul>
    
    <div>
    bla
    </div>
    

    Run pdoc on test script:

    pdoc markdown_test.py
    

    Gives this result in the browser: image

    Note, how the headings aren´t rendered correctly starting with the fenced python code block. If I remove the python syntax highlighting or the html <div> section at the end or even only the </div> marker at the very end of the test script, the result looks fine.

    System Information

    I encountered the problem first from a conda environment on windows when I tried to include a jupyter notebook exported to markdown into a project documentation. Then I tried on a linux machine with a conda environment and didn´t see the problem. But when I updated conda (conda update --all), the same issue came up. The update was from

    pdoc 12.0.2 + python 3.9.12
    

    to

    pdoc 12.0.2 + python 3.9.13
    

    (my windows conda also has the second version combination)

    In detail, the following packages were updated:

     _openmp_mutex                                   4.5-1_gnu --> 4.5-2_gnu
      alsa-lib                                 1.2.3-h516909a_0 --> 1.2.6.1-h7f98852_0
      anyio                                3.5.0-py39hf3d152e_0 --> 3.6.1-py39hf3d152e_0
      astroid            conda-forge::astroid-2.11.2-py39hf3d1~ --> pkgs/main::astroid-2.11.7-py39h06a4308_0
      attrs                                 21.4.0-pyhd8ed1ab_0 --> 22.1.0-pyh71513ae_1
      babel                                  2.9.1-pyh44b312d_0 --> 2.10.3-pyhd8ed1ab_0
      black                                 22.3.0-pyhd8ed1ab_0 --> 22.6.0-pyhd8ed1ab_0
      bleach                                 5.0.0-pyhd8ed1ab_0 --> 5.0.1-pyhd8ed1ab_0
      cffi                                1.15.0-py39h4bc2ebd_0 --> 1.15.1-py39he91dace_0
      charset-normalizer                    2.0.12-pyhd8ed1ab_0 --> 2.1.0-pyhd8ed1ab_0
      click                                8.1.2-py39hf3d152e_0 --> 8.1.3-py39hf3d152e_0
      colorama                               0.4.4-pyh9f0ad1d_0 --> 0.4.5-pyhd8ed1ab_0
      cryptography                        36.0.2-py39hd97740a_1 --> 37.0.4-py39hd97740a_0
      debugpy                              1.5.1-py39he80948d_0 --> 1.6.0-py39h5a03fae_0
      dill                                   0.3.4-pyhd8ed1ab_0 --> 0.3.5.1-pyhd8ed1ab_0
      executing                              0.8.3-pyhd8ed1ab_0 --> 0.9.1-pyhd8ed1ab_0
      fonttools                           4.32.0-py39hb9d737c_0 --> 4.34.4-py39hb9d737c_0
      gst-plugins-base                        1.20.1-hcf0ee16_1 --> 1.20.3-hf6a322e_0
      gstreamer                               1.20.1-hd4edc92_1 --> 1.20.3-hd4edc92_0
      icu                                       69.1-h9c3ff4c_0 --> 70.1-h27087fc_0
      importlib-metadata                  4.11.3-py39hf3d152e_1 --> 4.11.4-py39hf3d152e_0
      importlib_resourc~                     5.6.0-pyhd8ed1ab_0 --> 5.9.0-pyhd8ed1ab_0
      ipykernel          conda-forge/linux-64::ipykernel-6.9.2~ --> conda-forge/noarch::ipykernel-6.15.1-pyh210e3f2_0
      ipympl                                 0.8.8-pyhd8ed1ab_0 --> 0.9.1-pyhd8ed1ab_0
      ipython                              8.2.0-py39hf3d152e_0 --> 8.4.0-py39hf3d152e_0
      ipywidgets                             7.7.0-pyhd8ed1ab_0 --> 7.7.1-pyhd8ed1ab_0
      jinja2                                 3.1.1-pyhd8ed1ab_0 --> 3.1.2-pyhd8ed1ab_1
      jpeg                                        9e-h7f98852_0 --> 9e-h166bdaf_2
      jsonschema                             4.4.0-pyhd8ed1ab_0 --> 4.9.0-pyhd8ed1ab_0
      jupyter_client                         7.2.2-pyhd8ed1ab_1 --> 7.3.4-pyhd8ed1ab_0
      jupyter_core                         4.9.2-py39hf3d152e_0 --> 4.11.1-py39hf3d152e_0
      jupyter_server                        1.16.0-pyhd8ed1ab_1 --> 1.18.1-pyhd8ed1ab_0
      jupyterlab                             3.3.3-pyhd8ed1ab_0 --> 3.4.4-pyhd8ed1ab_0
      jupyterlab_pygmen~                     0.2.0-pyhd8ed1ab_0 --> 0.2.2-pyhd8ed1ab_0
      jupyterlab_server                     2.12.0-pyhd8ed1ab_0 --> 2.15.0-pyhd8ed1ab_0
      jupyterlab_widgets                     1.1.0-pyhd8ed1ab_0 --> 1.1.1-pyhd8ed1ab_0
      kiwisolver                           1.4.2-py39hf939315_1 --> 1.4.4-py39hf939315_0
      lerc                                       3.0-h9c3ff4c_0 --> 4.0.0-h27087fc_0
      libblas                         3.9.0-14_linux64_openblas --> 3.9.0-15_linux64_openblas
      libcblas                        3.9.0-14_linux64_openblas --> 3.9.0-15_linux64_openblas
      libclang                        13.0.1-default_hc23dcda_0 --> 14.0.6-default_h2e3cab8_0
      libdeflate                                1.10-h7f98852_0 --> 1.12-h166bdaf_0
      libgcc-ng                              11.2.0-h1d223b6_15 --> 12.1.0-h8d9b700_16
      libgfortran-ng                         11.2.0-h69a702a_15 --> 12.1.0-h69a702a_16
      libgfortran5                           11.2.0-h5c6108e_15 --> 12.1.0-hdcd56e2_16
      libglib                                 2.70.2-h174f98d_4 --> 2.72.1-h2d90d5f_0
      libgomp                                11.2.0-h1d223b6_15 --> 12.1.0-h8d9b700_16
      liblapack                       3.9.0-14_linux64_openblas --> 3.9.0-15_linux64_openblas
      libopenblas                    0.3.20-pthreads_h78a6416_0 --> 0.3.20-pthreads_h78a6416_1
      libpng                                  1.6.37-h21135ba_2 --> 1.6.37-h753d276_3
      libpq                                     14.2-hd57d9b9_0 --> 14.4-hd77ab85_0
      libstdcxx-ng                           11.2.0-he4da1e4_15 --> 12.1.0-ha89aaad_16
      libtiff                                  4.3.0-h542a066_3 --> 4.4.0-h0d92c0b_2
      libwebp                                  1.2.2-h3452ae3_0 --> 1.2.3-h522a892_1
      libwebp-base                             1.2.2-h7f98852_1 --> 1.2.3-h166bdaf_2
      libxml2                                 2.9.12-h885dcf4_1 --> 2.9.14-h22db469_3
      libxslt                                 1.1.33-h0ef7038_3 --> 1.1.35-h8affb1d_0
      libzlib                              1.2.11-h166bdaf_1014 --> 1.2.12-h166bdaf_2
      lxml                                 4.8.0-py39hb9d737c_1 --> 4.9.1-py39hb9d737c_0
      matplotlib-base                      3.5.1-py39h2fa2bec_0 --> 3.5.2-py39h700656a_1
      mysql-common                            8.0.28-haf5c9bc_3 --> 8.0.29-haf5c9bc_1
      mysql-libs                              8.0.28-h28c427c_3 --> 8.0.29-h28c427c_1
      nbclassic                              0.3.7-pyhd8ed1ab_0 --> 0.4.3-pyhd8ed1ab_0
      nbclient                              0.5.13-pyhd8ed1ab_0 --> 0.6.6-pyhd8ed1ab_0
      nbconvert                              6.4.5-pyhd8ed1ab_2 --> 6.5.0-pyhd8ed1ab_0
      nbconvert-core                         6.4.5-pyhd8ed1ab_2 --> 6.5.0-pyhd8ed1ab_0
      nbconvert-pandoc                       6.4.5-pyhd8ed1ab_2 --> 6.5.0-pyhd8ed1ab_0
      nbformat                               5.3.0-pyhd8ed1ab_0 --> 5.4.0-pyhd8ed1ab_0
      notebook                              6.4.10-pyha770c72_0 --> 6.4.12-pyha770c72_0
      nss                                       3.77-h2350873_0 --> 3.78-h2350873_0
      numpy                               1.22.3-py39h18676bf_1 --> 1.23.1-py39hba7629e_0
      openssl                                 1.1.1n-h166bdaf_0 --> 1.1.1q-h166bdaf_0
      pandas                               1.4.2-py39h1832856_0 --> 1.4.3-py39h1832856_0
      pandoc                                2.17.1.1-ha770c72_0 --> 2.18-ha770c72_0
      pillow                               9.1.0-py39hae2aec6_0 --> 9.2.0-py39hae2aec6_0
      pip                                   22.0.4-pyhd8ed1ab_0 --> 22.2.1-pyhd8ed1ab_0
      platformdirs                           2.5.1-pyhd8ed1ab_0 --> 2.5.2-pyhd8ed1ab_1
      prompt-toolkit                        3.0.29-pyha770c72_0 --> 3.0.30-pyha770c72_0
      psutil                               5.9.0-py39hb9d737c_1 --> 5.9.1-py39hb9d737c_0
      pylint                                2.13.5-pyhd8ed1ab_0 --> 2.14.5-pyhd8ed1ab_0
      pyparsing                              3.0.7-pyhd8ed1ab_0 --> 3.0.9-pyhd8ed1ab_0
      pyqt                                5.12.3-py39hf3d152e_8 --> 5.15.7-py39h18e9c17_0
      pyqt5-sip                          4.19.18-py39he80948d_8 --> 12.11.0-py39h5a03fae_0
      python                          3.9.12-h9a8a25e_1_cpython --> 3.9.13-h9a8a25e_0_cpython
      python-fastjsonsc~                    2.15.3-pyhd8ed1ab_0 --> 2.16.1-pyhd8ed1ab_0
      pyzmq                               22.3.0-py39headdf64_2 --> 23.2.0-py39headdf64_0
      readline                                   8.1-h46c0cb4_0 --> 8.1.2-h0f457ee_0
      requests                              2.27.1-pyhd8ed1ab_0 --> 2.28.1-pyhd8ed1ab_0
      ruamel_yaml                     0.15.80-py39h3811e60_1006 --> 0.15.80-py39hb9d737c_1007
      scipy                                1.8.0-py39hee8e79c_1 --> 1.9.0-py39h8ba3f38_0
      setuptools                          62.0.0-py39hf3d152e_0 --> 63.3.0-py39hf3d152e_0
      soupsieve                              2.3.1-pyhd8ed1ab_0 --> 2.3.2.post1-pyhd8ed1ab_0
      sqlite                                  3.37.1-h4ff8645_0 --> 3.39.2-h4ff8645_0
      stack_data                             0.2.0-pyhd8ed1ab_0 --> 0.3.0-pyhd8ed1ab_0
      terminado                           0.13.3-py39hf3d152e_1 --> 0.15.0-py39hf3d152e_0
      tornado                                6.1-py39hb9d737c_3 --> 6.2-py39hb9d737c_0
      traitlets                              5.1.1-pyhd8ed1ab_0 --> 5.3.0-pyhd8ed1ab_0
      typed-ast                            1.5.2-py39h3811e60_0 --> 1.5.4-py39hb9d737c_0
      typing-extensions                        4.1.1-hd8ed1ab_0 --> 4.3.0-hd8ed1ab_0
      typing_extensions                      4.1.1-pyha770c72_0 --> 4.3.0-pyha770c72_0
      urllib3                               1.26.9-pyhd8ed1ab_0 --> 1.26.11-pyhd8ed1ab_0
      websocket-client                       1.3.2-pyhd8ed1ab_0 --> 1.3.3-pyhd8ed1ab_0
      widgetsnbextension conda-forge/linux-64::widgetsnbextens~ --> conda-forge/noarch::widgetsnbextension-3.6.1-pyha770c72_0
      wrapt                               1.14.0-py39hb9d737c_1 --> 1.14.1-py39hb9d737c_0
      zlib                                 1.2.11-h166bdaf_1014 --> 1.2.12-h166bdaf_2
      zstd                                     1.5.2-ha95c52a_0 --> 1.5.2-h8a70e8d_2
    
    bug 
    opened by tmeyier 1
  • Avoid expansion of typenames into long expressions, e.g., `numpy.typing.ArrayLike`

    Avoid expansion of typenames into long expressions, e.g., `numpy.typing.ArrayLike`

    Packages often include typenames that expand to long Union[...] definitions. Examples include ArrayLike and DTypeLike from numpy.typing (see here)

    For this sample program

    from typing import Any
    
    import numpy as np
    import numpy.typing as npt
    
    def f1(a: npt.ArrayLike, dtype: npt.DTypeLike) -> np.ndarray[Any, Any]:
      return np.asarray(a).astype(dtype)
    

    the pdoc output looks awful:

    def f1(
    	array: Union[numpy._array_like._SupportsArray[numpy.dtype], numpy._nested_sequence._NestedSequence[numpy._array_like._SupportsArray[numpy.dtype]], bool, int, float, complex, str, bytes, numpy._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]],
    	dtype: Union[numpy.dtype[Any], NoneType, Type[Any], numpy._dtype_like._SupportsDType[numpy.dtype[Any]], str, Tuple[Any, int], Tuple[Any, Union[SupportsIndex, Sequence[SupportsIndex]]], List[Any], numpy._dtype_like._DTypeDict, Tuple[Any, Any]]
    ) -> numpy.ndarray[typing.Any, typing.Any]:
    

    Is there any way to direct pdoc to show shorter typenames?

    • We cannot use typing.NewType or typing.TypeVar because the Union[...] is not subclassable.

    • Assigning the type to a local constant unfortunately does not help:

    ArrayLike = npt.ArrayLike
    
    • Similarly, declaring a local TypeAlias also does not help:
    import typing
    ArrayLike: typing.TypeAlias = npt.ArrayLike
    
    • Even the ugly approach of deferring the type using a string does not help:
    def f2(a: 'npt.ArrayLike', dtype: 'npt.DTypeLike') -> np.ndarray[Any, Any]: ...
    

    Can you think of any other workaround or solution? Ideally, any local typename constant could remain unexpanded. (TypeAlias is not ideal because it only appears in Python 3.10.) Possibly look for pdoc metadata within typing.Annotated?

    enhancement 
    opened by hhoppe 9
  • Improve handling of camelCase and snake_case when searching documentation

    Improve handling of camelCase and snake_case when searching documentation

    Problem Description

    When I am searching for the documentation for a function, say fooBarFunction(), I will often type foo bar function into the search box in order to save time. When I do this, the function will often be significantly lower in the results list, even if what I have typed is an exact match (excluding the way words are split).

    Proposal

    Searching for a function using multiple words should prioritise functions with that exact name, even if the function uses a different capitalisation convention to the search query.

    Additional context

    The correct result is 7th in the list image

    If I have time, I'll be happy to work on a PR for this.

    enhancement 
    opened by MiguelGuthridge 2
This is a repository for "100 days of code challenge" projects. You can reach all projects from beginner to professional which are written in Python.

100 Days of Code It's a challenge that aims to gain code practice and enhance programming knowledge. Day #1 Create a Band Name Generator It's actually

SelenNB 2 May 12, 2022
📖 Generate markdown API documentation from Google-style Python docstring. The lazy alternative to Sphinx.

lazydocs Generate markdown API documentation for Google-style Python docstring. Getting Started • Features • Documentation • Support • Contribution •

Machine Learning Tooling 93 Aug 5, 2022
Automated Integration Testing and Live Documentation for your API

Automated Integration Testing and Live Documentation for your API

ScanAPI 1.2k Jul 29, 2022
Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.

Introduction Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without

Swagger 22.5k Aug 12, 2022
A curated list of awesome tools for Sphinx Python Documentation Generator

Awesome Sphinx (Python Documentation Generator) A curated list of awesome extra libraries, software and resources for Sphinx (Python Documentation Gen

Hyunjun Kim 807 Aug 13, 2022
Run `black` on python code blocks in documentation files

blacken-docs Run black on python code blocks in documentation files. install pip install blacken-docs usage blacken-docs provides a single executable

Anthony Sottile 415 Aug 6, 2022
Main repository for the Sphinx documentation builder

Sphinx Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects (or other documents consisting of mul

null 4.8k Aug 9, 2022
Literate-style documentation generator.

888888b. 888 Y88b 888 888 888 d88P 888 888 .d8888b .d8888b .d88b. 8888888P" 888 888 d88P" d88P" d88""88b 888 888 888

Pycco 793 Aug 13, 2022
Main repository for the Sphinx documentation builder

Sphinx Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects (or other documents consisting of mul

null 4.8k Aug 13, 2022
Project documentation with Markdown.

MkDocs Project documentation with Markdown. View the MkDocs documentation. Project release notes. Visit the MkDocs wiki for community resources, inclu

MkDocs 14.7k Aug 10, 2022
Watch a Sphinx directory and rebuild the documentation when a change is detected. Also includes a livereload enabled web server.

sphinx-autobuild Rebuild Sphinx documentation on changes, with live-reload in the browser. Installation sphinx-autobuild is available on PyPI. It can

Executable Books 415 Aug 8, 2022
Your Project with Great Documentation.

Read Latest Documentation - Browse GitHub Code Repository The only thing worse than documentation never written, is documentation written but never di

Timothy Edmund Crosley 793 Aug 9, 2022
:blue_book: Automatic documentation from sources, for MkDocs.

mkdocstrings Automatic documentation from sources, for MkDocs. Features Python handler features Requirements Installation Quick usage Features Languag

Timothée Mazzucotelli 812 Aug 6, 2022
:blue_book: Automatic documentation from sources, for MkDocs.

mkdocstrings Automatic documentation from sources, for MkDocs. Features - Python handler - Requirements - Installation - Quick usage Features Language

null 815 Aug 15, 2022
Seamlessly integrate pydantic models in your Sphinx documentation.

Seamlessly integrate pydantic models in your Sphinx documentation.

Franz Wöllert 58 Jul 17, 2022
Documentation generator for C++ based on Doxygen and mosra/m.css.

mosra/m.css is a Doxygen-based documentation generator that significantly improves on Doxygen's default output by controlling some of Doxygen's more unruly options, supplying it's own slick HTML+CSS generation and adding a fantastic live search feature.

Mark Gillard 73 Aug 10, 2022
NetBox plugin for BGP related objects documentation

Netbox BGP Plugin Netbox plugin for BGP related objects documentation. Compatibility This plugin in compatible with NetBox 2.10 and later. Installatio

Nikolay Yuzefovich 105 Aug 7, 2022
Documentation of the QR code found on new Austrian ID cards.

Austrian ID Card QR Code This document aims to be a complete documentation of the format used in the QR area on the back of new Austrian ID cards (Per

Gabriel Huber 10 Jul 27, 2022
Swagger Documentation Generator for Django REST Framework: deprecated

Django REST Swagger: deprecated (2019-06-04) This project is no longer being maintained. Please consider drf-yasg as an alternative/successor. I haven

Marc Gibbons 2.6k Aug 8, 2022