spirali/nedoc

Generator of API documentation for Python

About me 🧚‍♀️

• I am a developer and research engineer at ACS Research Group and IT4Innovations.
• I am interested in AI Safety, HPC, and formal verification.
• I have PhD in Computer Science.
• I work mostly in Rust and Python; sometimes in TypeScript. In past C, C++, Haskell.
• I love digital painting and playing the cello.

Selected projects where I am main author/co-author

• HyperQueue - user-friendly and scalable job scheduler for supercomputers
• Nelsie - slide making software
• Rain - framework for large distributed pipelines
• Interlab - toolkit for multi-agent interactions
• RSDS - Dask server reimplemented in Rust
• Nedoc - non-evaluating documentation generator for Python
• Haydi - Python framework for generating discrete structures)
• Aislinn - dynamic verifier for MPI programs
• Estee - simulator for task-based workflow schedulers
• ORCO - Python package for defining, executing, and persisting computations
• Replay-cache - replay cache for LangChain
• RMahjong - Riichi Mahjong
• LabLab - A simple image anotation tool

nedoc's Issues

Improvement to reporting exceptions during build

Currently, when an exeption happens during a build, the raw exception is printed. I suggest catching the exception and printing additionally the file that it happened in.

E.g. during nedoc run on my project it encountered an unsupported character. Actual output (attached) unfortunately doesn't tell me when to look for it to correct.

$ python -m nedoc build
parsing: 1%|███▍ | 43/3366 [00:01<06:07, 9.05it/s]multiprocessing.pool.RemoteTraceback:
"""
Traceback (most recent call last):
File "C:\Python36_x86\python-3.6.1\lib\multiprocessing\pool.py", line 119, in worker
result = (True, func(*args, **kwds))
File "C:\Python36_x86\python-3.6.1\lib\site-packages\nedoc\parse.py", line 108, in parse_path
code = f.read()
File "C:\Python36_x86\python-3.6.1\lib\encodings\cp1250.py", line 23, in decode
return codecs.charmap_decode(input,self.errors,decoding_table)[0]
UnicodeDecodeError: 'charmap' codec can't decode byte 0x81 in position 308: character maps to
"""

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
File "C:\Python36_x86\python-3.6.1\lib\runpy.py", line 193, in _run_module_as_main
"main", mod_spec)
File "C:\Python36_x86\python-3.6.1\lib\runpy.py", line 85, in run_code
exec(code, run_globals)
File "C:\Python36_x86\python-3.6.1\lib\site-packages\nedoc_main.py", line 4, in
main()
File "C:\Python36_x86\python-3.6.1\lib\site-packages\nedoc\cmd.py", line 72, in main
c.build()
File "C:\Python36_x86\python-3.6.1\lib\site-packages\nedoc\core.py", line 111, in build
self.build_modules()
File "C:\Python36_x86\python-3.6.1\lib\site-packages\nedoc\core.py", line 97, in build_modules
zip(paths, processed), total=len(paths), desc="parsing"):
File "C:\Python36_x86\python-3.6.1\lib\site-packages\tqdm_tqdm.py", line 833, in iter
for obj in iterable:
File "C:\Python36_x86\python-3.6.1\lib\multiprocessing\pool.py", line 699, in next
raise value
UnicodeDecodeError: 'charmap' codec can't decode byte 0x81 in position 308: character maps to

Links in HTML broken if there is a space in project path

My Python source folder has a space in it's name (Python Scripts). Building documentation results in broken links in HTML - the browser can't find a proper page.

Affected link example:
<a class="symbol" href="Python Scripts.python_functions.base.log.html">log</a>

Clicking on the link results in browser's attempt to open "Python" page - which does not exist.

UX improvements

• Show list of links to subclasses of a class
• Unify breadcrumbs (for modules) and add missing ones (for source code)
• Add source code links to specific lines
• Separate static methods to a different table
• Add expander icon (arrow) to classes in menu
• Remove standalone function pages, replace with links
• Add expander with complete doc comment to functions (together with link to source and import/override list)
• Improve UX of [imported] attributes (move them to a different place)
• Move docstring from init to the whole class (if class has no docstring)
• Improve keyword contrast and colors
• Reduce menu size (Javascript menu?)
• Parse reStructured text (links to classes and functions)

Attempt to make a symlink on Windows

nedoc attempts to make a symlink on Windows (at the end of writesrc step), what results in OSError: symbolic link privilege not held.

OS: Win10 Enteprise, build 16299
Regular user (no admin rights)