Literate-style documentation generator.

pycco-docs, updated 🕥 2022-01-21 18:17:35

888888b. 888 Y88b 888 888 888 d88P 888 888 .d8888b .d8888b .d88b. 8888888P" 888 888 d88P" d88P" d88""88b 888 888 888 888 888 888 888 888 Y88b 888 Y88b. Y88b. Y88..88P 888 "Y88888 "Y8888P "Y8888P "Y88P" 888 Y8b d88P "Y88P"

Pycco is a Python port of Docco: the original quick-and-dirty, hundred-line- long, literate-programming-style documentation generator. For more information, see:

https://pycco-docs.github.io/pycco/

Others:

CoffeeScript (Original) - http://jashkenas.github.com/docco/

Ruby - http://rtomayko.github.com/rocco/

Sh - http://rtomayko.github.com/shocco/

Build Status Coverage Status

Issues

Switch to pathlib (py3 stdlib module)

opened on 2022-01-21 18:17:35 by hv10

As Python2 is long overdue to be phased-out I switched the os.path module to use the recommended pathlib module instead - and through that fixing the watcher which did no longer work for me.

The first commit just reformats everything with black (if thats an issue let me know then I could potentially "undo" that).

Imports blow up in pystache

opened on 2021-12-05 04:50:23 by matthewdeanmartin

``` [email protected] MINGW64 ~/GitHub/no_algo_twitter (main) $ pycco src/*.py Traceback (most recent call last): File "C:\Users\matth\AppData\Local\Programs\Python\Python38\lib\runpy.py", line 194, in _run_module_as_main return _run_code(code, main_globals, None, File "C:\Users\matth\AppData\Local\Programs\Python\Python38\lib\runpy.py", line 87, in _run_code exec(code, run_globals) File "C:\Users\matth.virtualenvs\no_algo_twitter-Vk_lV-hQ\Scripts\pycco.exe__main__.py", line 4, in File "C:\Users\matth.virtualenvs\no_algo_twitter-Vk_lV-hQ\lib\site-packages\pycco__init__.py", line 1, in from .main import * # noqa File "C:\Users\matth.virtualenvs\no_algo_twitter-Vk_lV-hQ\lib\site-packages\pycco\main.py", line 60, in from pycco.generate_index import generate_index File "C:\Users\matth.virtualenvs\no_algo_twitter-Vk_lV-hQ\lib\site-packages\pycco\generate_index.py", line 9, in from pycco_resources import pycco_template File "C:\Users\matth.virtualenvs\no_algo_twitter-Vk_lV-hQ\lib\site-packages\pycco_resources__init__.py", line 1, in import pystache File "C:\Users\matth.virtualenvs\no_algo_twitter-Vk_lV-hQ\lib\site-packages\pystache__init__.py", line 2, in from init import * ModuleNotFoundError: No module named 'init'

[email protected] MINGW64 ~/GitHub/no_algo_twitter (main) $ python --version Python 3.8.7

``` I think it is blowing up on some really old school import syntax. I don't remember seeing that sort of import that omits the package name since python 2.

There is some motion to take over pystache ref: https://github.com/pypa/pypi-support/issues/1422 and we could see new releases of pystache, but in the meanwhile, pycco seems to be broken in a lot of venvs.

Docstring that ends with""" rather than \n""" completely breaks rendering

opened on 2021-09-17 10:24:56 by Pet3ris

Hi There,

Thanks for this awesome tool. Running into an issue where these docstrings break rendering:

python def add(x, y): """This should be a simple docstring However, it turns everything following it into a comment.""" return x + y

Only this works:

python def add(x, y): """This should be a simple docstring However, it turns everything following it into a comment. """ return x + y

Given this particular formatting is not picked up on by pylint, I assume it is valid and this is a bug.

ClassNotFound('no lexer . . .

opened on 2021-05-11 23:21:19 by brucebookman

Not sure what the root cause is here

Traceback (most recent call last): File "/usr/local/bin/pycco", line 33, in <module> sys.exit(load_entry_point('Pycco==0.6.0', 'console_scripts', 'pycco')()) File "/usr/local/bin/pycco", line 25, in importlib_load_entry_point return next(matches).load() File "/usr/local/Cellar/[email protected]/3.9.5/Frameworks/Python.framework/Versions/3.9/lib/python3.9/importlib/metadata.py", line 77, in load module = import_module(match.group('module')) File "/usr/local/Cellar/[email protected]/3.9.5/Frameworks/Python.framework/Versions/3.9/lib/python3.9/importlib/__init__.py", line 127, in import_module return _bootstrap._gcd_import(name[level:], package, level) File "<frozen importlib._bootstrap>", line 1030, in _gcd_import File "<frozen importlib._bootstrap>", line 1007, in _find_and_load File "<frozen importlib._bootstrap>", line 972, in _find_and_load_unlocked File "<frozen importlib._bootstrap>", line 228, in _call_with_frames_removed File "<frozen importlib._bootstrap>", line 1030, in _gcd_import File "<frozen importlib._bootstrap>", line 1007, in _find_and_load File "<frozen importlib._bootstrap>", line 986, in _find_and_load_unlocked File "<frozen importlib._bootstrap>", line 664, in _load_unlocked File "<frozen importlib._bootstrap>", line 627, in _load_backward_compatible File "<frozen zipimport>", line 259, in load_module File "/usr/local/lib/python3.9/site-packages/Pycco-0.6.0-py3.9.egg/pycco/__init__.py", line 1, in <module> # -*- coding: utf-8 -*- File "<frozen importlib._bootstrap>", line 1007, in _find_and_load File "<frozen importlib._bootstrap>", line 986, in _find_and_load_unlocked File "<frozen importlib._bootstrap>", line 664, in _load_unlocked File "<frozen importlib._bootstrap>", line 627, in _load_backward_compatible File "<frozen zipimport>", line 259, in load_module File "/usr/local/lib/python3.9/site-packages/Pycco-0.6.0-py3.9.egg/pycco/main.py", line 373, in <module> File "/usr/local/lib/python3.9/site-packages/Pycco-0.6.0-py3.9.egg/pycco/main.py", line 369, in compile_language File "/usr/local/lib/python3.9/site-packages/pygments/lexers/__init__.py", line 93, in get_lexer_by_name raise ClassNotFound('no lexer for alias %r found' % _alias) pygments.util.ClassNotFound: no lexer for alias 'stata' found

Bump pygments from 2.5.2 to 2.7.4

opened on 2021-03-29 17:53:39 by dependabot[bot]

Bumps pygments from 2.5.2 to 2.7.4.

Release notes

Sourced from pygments's releases.

2.7.4

  • Updated lexers:

    • Apache configurations: Improve handling of malformed tags (#1656)

    • CSS: Add support for variables (#1633, #1666)

    • Crystal (#1650, #1670)

    • Coq (#1648)

    • Fortran: Add missing keywords (#1635, #1665)

    • Ini (#1624)

    • JavaScript and variants (#1647 -- missing regex flags, #1651)

    • Markdown (#1623, #1617)

    • Shell

      • Lex trailing whitespace as part of the prompt (#1645)
      • Add missing in keyword (#1652)

    • SQL - Fix keywords (#1668)

    • Typescript: Fix incorrect punctuation handling (#1510, #1511)

  • Fix infinite loop in SML lexer (#1625)

  • Fix backtracking string regexes in JavaScript/TypeScript, Modula2 and many other lexers (#1637)

  • Limit recursion with nesting Ruby heredocs (#1638)

  • Fix a few inefficient regexes for guessing lexers

  • Fix the raw token lexer handling of Unicode (#1616)

  • Revert a private API change in the HTML formatter (#1655) -- please note that private APIs remain subject to change!

  • Fix several exponential/cubic-complexity regexes found by Ben Caller/Doyensec (#1675)

  • Fix incorrect MATLAB example (#1582)

Thanks to Google's OSS-Fuzz project for finding many of these bugs.

2.7.3

... (truncated)

Changelog

Sourced from pygments's changelog.

Version 2.7.4

(released January 12, 2021)

  • Updated lexers:

    • Apache configurations: Improve handling of malformed tags (#1656)

    • CSS: Add support for variables (#1633, #1666)

    • Crystal (#1650, #1670)

    • Coq (#1648)

    • Fortran: Add missing keywords (#1635, #1665)

    • Ini (#1624)

    • JavaScript and variants (#1647 -- missing regex flags, #1651)

    • Markdown (#1623, #1617)

    • Shell

      • Lex trailing whitespace as part of the prompt (#1645)
      • Add missing in keyword (#1652)

    • SQL - Fix keywords (#1668)

    • Typescript: Fix incorrect punctuation handling (#1510, #1511)

  • Fix infinite loop in SML lexer (#1625)

  • Fix backtracking string regexes in JavaScript/TypeScript, Modula2 and many other lexers (#1637)

  • Limit recursion with nesting Ruby heredocs (#1638)

  • Fix a few inefficient regexes for guessing lexers

  • Fix the raw token lexer handling of Unicode (#1616)

  • Revert a private API change in the HTML formatter (#1655) -- please note that private APIs remain subject to change!

  • Fix several exponential/cubic-complexity regexes found by Ben Caller/Doyensec (#1675)

  • Fix incorrect MATLAB example (#1582)

Thanks to Google's OSS-Fuzz project for finding many of these bugs.

Version 2.7.3

(released December 6, 2020)

... (truncated)

Commits
  • 4d555d0 Bump version to 2.7.4.
  • fc3b05d Update CHANGES.
  • ad21935 Revert "Added dracula theme style (#1636)"
  • e411506 Prepare for 2.7.4 release.
  • 275e34d doc: remove Perl 6 ref
  • 2e7e8c4 Fix several exponential/cubic complexity regexes found by Ben Caller/Doyensec
  • eb39c43 xquery: fix pop from empty stack
  • 2738778 fix coding style in test_analyzer_lexer
  • 02e0f09 Added 'ERROR STOP' to fortran.py keywords. (#1665)
  • c83fe48 support added for css variables (#1633)
  • Additional commits viewable in compare view


Dependabot compatibility score

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

Dependabot commands and options
You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot merge` will merge this PR after your CI passes on it - `@dependabot squash and merge` will squash and merge this PR after your CI passes on it - `@dependabot cancel merge` will cancel a previously requested merge and block automerging - `@dependabot reopen` will reopen this PR if it is closed - `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself) - `@dependabot use these labels` will set the current labels as the default for future PRs for this repo and language - `@dependabot use these reviewers` will set the current reviewers as the default for future PRs for this repo and language - `@dependabot use these assignees` will set the current assignees as the default for future PRs for this repo and language - `@dependabot use this milestone` will set the current milestone as the default for future PRs for this repo and language You can disable automated security fix PRs for this repo from the [Security Alerts page](https://github.com/pycco-docs/pycco/network/alerts).

Pycco is unable to determine syntax for a Python3-formatted file without an appropriate extension

opened on 2020-10-06 12:19:43 by zachriggle

When running pycco file, it works well when the file is named foo.py, but does not work for foo despite having a shebang.

Example Script

Create this file as example. Note that if it is named example.py, everything works as expected.

```python

!/usr/bin/env python3

import os

class CommandLineFlag(object): '''Holds information about a command-line argument''' ```

Pycco Output

``` $ pycco example Traceback (most recent call last): File "/Users/zachriggle/Library/Python/3.8/lib/python/site-packages/pycco/main.py", line 397, in get_language raise ValueError() ValueError

During handling of the above exception, another exception occurred:

Traceback (most recent call last): File "/Users/zachriggle/Library/Python/3.8/bin/pycco", line 10, in sys.exit(main()) File "/Users/zachriggle/Library/Python/3.8/lib/python/site-packages/pycco/main.py", line 629, in main process(args.sources, outdir=outdir, preserve_paths=args.paths, File "/Users/zachriggle/Library/Python/3.8/lib/python/site-packages/pycco/main.py", line 533, in process next_file() File "/Users/zachriggle/Library/Python/3.8/lib/python/site-packages/pycco/main.py", line 518, in next_file f.write(generate_documentation(s, preserve_paths=preserve_paths, File "/Users/zachriggle/Library/Python/3.8/lib/python/site-packages/pycco/main.py", line 80, in generate_documentation return _generate_documentation(source, code, outdir, preserve_paths, language) File "/Users/zachriggle/Library/Python/3.8/lib/python/site-packages/pycco/main.py", line 87, in _generate_documentation language = get_language(file_path, code, language_name=language) File "/Users/zachriggle/Library/Python/3.8/lib/python/site-packages/pycco/main.py", line 402, in get_language raise ValueError("Can't figure out the language!") ValueError: Can't figure out the language! ```

Releases

--skip-bad-files now skips all kind of bad files 2018-05-02 14:04:38

This release includes some code modernization and greater test coverage, plus:

  • one new feature, courtesy of @vrde: --skip-bad-files, also now aliased to --ignore-errors, does what it says on the tin: Pycco will continue operation if it encounters a file it does not understand.
  • three Markdown enhancements are available: smartypants (which, contrary to the documentation, wasn't enabled before), fenced code blocks, and footnotes.

0.5.1 - Directory recursion 2016-06-04 18:49:15

Changes: - Courtesy of @goosemo, Pycco will recurse into directories given as arguments and attempt to process all the contents. - Added -s argument to continue processing a list of files (or directory) if an unprocessable file is encountered.

Sitemaps 2015-12-28 19:53:12

Generate a simple index of all generated documentation using the -i flag. Many thanks to @abbgrade for his contribution to Pycco.

0.3.1 2015-11-20 01:10:11

  • Bugfixes
  • Specify language
Pycco

A Python port of docco, originally by @fitzgen.

GitHub Repository Homepage