search

mitmproxy / pdoc

API Documentation for Python Projects
https://pdoc.dev
MIT No Attribution
1.96k stars 193 forks source link

`AssertionError: OSError: If there is an error while writing to the file.` Help would be appreciated #689

Closed MartinRJDagleish closed 6 months ago

MartinRJDagleish commented 6 months ago

Problem Description

AssertionError:     OSError: If there is an error while writing to the file.

Is raised, when I run pdoc with the following flags

pdoc --math -d numpy -t ./docs/template -o ./docs/html smPyFLIM
Full stacktrace ```bash Traceback (most recent call last): File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/bin/pdoc", line 8, in sys.exit(cli()) ^^^^^ File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/__main__.py", line 199, in cli pdoc.pdoc( File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/__init__.py", line 513, in pdoc out = render.html_module(module, all_modules) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/usr/lib/python3.11/contextlib.py", line 81, in inner return func(*args, **kwds) ^^^^^^^^^^^^^^^^^^^ File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/render.py", line 106, in html_module return env.get_template("module.html.jinja2").render( ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/jinja2/environment.py", line 1304, in render self.environment.handle_exception() File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/jinja2/environment.py", line 939, in handle_exception raise rewrite_traceback_stack(source=source) File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/templates/default/module.html.jinja2", line 311, in top-level template code {%- if loop.nextitem -%} ^^^^^^^^^^^^^^^^^ File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/templates/default/frame.html.jinja2", line 36, in top-level template code {% block body %} ^^^^^^^^^^^^^^^^^ File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/templates/default/frame.html.jinja2", line 42, in block 'body' {% block content %}{% endblock %} ^^^^^^^^^^^^^^^^^^^^^^^^^ File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/templates/default/module.html.jinja2", line 101, in block 'content' {% block module_contents %} ^^^^^^^^^^^^^^^^^^^^^ File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/templates/default/module.html.jinja2", line 108, in block 'module_contents' {{ member(m) }} File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/jinja2/runtime.py", line 782, in _invoke rv = self._func(*arguments) ^^^^^^^^^^^^^^^^^^^^^^ File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/templates/default/module.html.jinja2", line 208, in template {{ docstring(doc) }} ^^^^^^^^^^^^^^^^^^^^^^^^^ File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/jinja2/runtime.py", line 782, in _invoke rv = self._func(*arguments) ^^^^^^^^^^^^^^^^^^^^^^ File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/templates/default/module.html.jinja2", line 212, in template
{{ var.docstring | replace("@public", "") | to_markdown | to_html | linkify(namespace=var.qualname) }}
^^^^^^^^^^^^^^^^^^^^^ File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/render_helpers.py", line 192, in to_markdown_with_context return to_markdown(docstring, module, docformat) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/render_helpers.py", line 197, in to_markdown return docstrings.convert(docstring, docformat, module.source_file) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/docstrings.py", line 42, in convert docstring = numpy(docstring) ^^^^^^^^^^^^^^^^ File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/docstrings.py", line 198, in numpy contents += f"###### {heading}\n{_numpy_parameters(content)}" ^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/docstrings.py", line 226, in _numpy_parameters for item in _indented_list(content): ^^^^^^^^^^^^^^^^^^^^^^^ File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/docstrings.py", line 149, in _indented_list assert not contents.startswith(" "), contents AssertionError: OSError: If there is an error while writing to the file. ```

I am not quite sure, what causes this issues and I am not quite sure, what the stacktrace should tell me. Why would there be a problem, while writing to the file?

If the template file, helps that I use, here it is:

Template File for math with `KaTeX` ```jinja2 {# This template is included in math mode and loads MathJax for formula rendering. #} {# #} ```

I am not a web dev, so please excuse my bad template code. I just briefly put this togehter to have KaTeX support instead of MathJax (I wanted the lightweight and fast rendering).

Steps to reproduce the behavior

System Information

Paste the output of "pdoc --version" here.

> pdoc --version 
pdoc: 14.4.0
Python: 3.11.8
Platform: Linux-6.6.26-1-MANJARO-x86_64-with-glibc2.39
MartinRJDagleish commented 6 months ago

Solution

I debugged the pdoc code base with the flags from above and then stepped throug the doc generation. There I noticed, that the crash was always happening in a certain module.

I investigated my code further and after some examination, I found that my docstring was wrongly formatted (not according to numpydoc format).

Error inducing code snippet (shortened):

class Foo:
    @classmethod
    def ser_and_write_to_file(cls, fit_sett: FitSett, fpath: Path | str) -> None:
        """
        Write the serialized representation of the `fit_sett` object to a file specified by `fpath`.

        Parameters
        ----------
        fit_sett: FitSett
            The object to be serialized and written to the file.
        fpath: Path | str
            The path to the file where the serialized representation will be written.

        Raises
        ------
            OSError: If there is an error while writing to the file.

        Returns
        -------
        None
        """

instead of the correct: 

class Foo:
    @classmethod
    def ser_and_write_to_file(cls, fit_sett: FitSett, fpath: Path | str) -> None:
        """
        Write the serialized representation of the `fit_sett` object to a file specified by `fpath`.

        Parameters
        ----------
        fit_sett: FitSett
            The object to be serialized and written to the file.
        fpath: Path | str
            The path to the file where the serialized representation will be written.

        Raises
        ------
        OSError
            If there is an error while writing to the file.

        Returns
        -------
        None
        """

I think I got some docstring style wrong or just did not notice. Anyways this fixes the issue now.