Literate-style documentation generator.

If a module has a docstring, e.g.

"""
This is the docstring
"""

print "module code starts here"

the docstring isn't converted properly.

I'd like to import the pycco module in my own python build script, but currently there are a few show stoppers:

• there is no "entry point" function for pycco doc generation that I could invoke from my script (e.g. pycco.generate_docs(path_to_scriptdir))
• pycco assumes that you have cd'ed to your script directory before generating the docs, it can't handle absolute or relative paths... this isn't possible in build scripts
• there should be an option to specify the output path of the docs.

I had some problems running pycco in a directory containing some cached Pytest files (.pytest_cache/). I noticed that even if the --skip-bad-files option was used, Pycco would still fail to generate the documentation. Removing the cached files is an option of course, but in my opinion Pycco should treat those files as bad files.

Given a .pytest_cache dire.tory (AFAIK it should be generate by Pytest when running the tests), the new behavior is the following,

With the --skip-bad-files option

 ~/r/pycco git:(master) ✗ ➜ pycco --skip-bad-files  .pytest_cache/
pycco [FAILURE]: .pytest_cache/v/cache/lastfailed, Can't figure out the language!
pycco [FAILURE]: .pytest_cache/v/cache/nodeids, Can't figure out the language!

Without the --skip-bad-files option

 ~/r/pycco git:(master) ✗ ➜ pycco .pytest_cache/
Traceback (most recent call last):
  File "/home/vrde/repos/pycco/pycco/main.py", line 392, in get_language
    lang = lexers.guess_lexer(code).name.lower()
  File "/home/vrde/.local/share/virtualenvs/1e40936ec5d4128/lib/python3.6/site-packages/pygments/lexers/__init__.py", line 252, in guess_lexer
    raise ClassNotFound('no lexer matching the text found')
pygments.util.ClassNotFound: no lexer matching the text found

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/vrde/.local/share/virtualenvs/1e40936ec5d4128/bin/pycco", line 11, in <module>
    load_entry_point('Pycco', 'console_scripts', 'pycco')()
  File "/home/vrde/repos/pycco/pycco/main.py", line 620, in main
    skip=opts.skip_bad_files)
  File "/home/vrde/repos/pycco/pycco/main.py", line 532, in process
    next_file()
  File "/home/vrde/repos/pycco/pycco/main.py", line 520, in next_file
    encoding=encoding))
  File "/home/vrde/repos/pycco/pycco/main.py", line 65, in generate_documentation
    return _generate_documentation(source, code, outdir, preserve_paths, language)
  File "/home/vrde/repos/pycco/pycco/main.py", line 72, in _generate_documentation
    language = get_language(file_path, code, language=language)
  File "/home/vrde/repos/pycco/pycco/main.py", line 402, in get_language
    raise ValueError("Can't figure out the language!")
ValueError: Can't figure out the language!

When I parse this docstring

"""
This is the first code sample

    alpha

This is the second code sample

    gamma
"""

... I get the following format:

This is the first code sample

alpha

This is the second code sample

gamma

But if I indent the second code block further, like this:

"""
This is the first code sample

    alpha

This is the second code sample

        gamma
"""

... I get the desired output:

This is the first code sample

alpha

This is the second code sample

gamma

The problem vanishes if https://github.com/fitzgen/pycco/blob/master/pycco/main.py#L128 is changed from

last_scope = current_scope if current_scope > last_scope else last_scope

... to ...

last_scope = current_scope

Is this a valid change? Or would it break something?

Regards Anand

I just installed pycco using pip and was wondering why the background was not staying behind the code when scrolling horizontally, which was fixed over a year ago. It turns out there hasn't been a new version for quite some time :) It'd be great if a new version could be released!

:shipit:

Steps

1. Install pycco using pip install pycco (Dependencies such as pygments, pystache, etc are installed)
2. cd /usr/local/lib/python2.6/dist-packages/pycco (As one example).
3. Run pycco main.py (That is to say, run pycco against the pycco source)

Expected results

Page identical to http://fitzgen.github.com/pycco/ appears.

Actual results

I believe this page is getting generated correctly, EXCEPT that all the <> in the HTML are being escaped (presumably by pystache) into < and >, so the page is more-or-less the raw HTML instead of the rendered HTML. The pypi package of pystache was updated 3-25-12, so I'm guessing this is what has caused pycco to fail. I haven't looked into whether this is a bug on the pystache side as opposed to the pycco side.

Notes

My guess is that pycco is just not using the un-escaping versions of mustache tags {{&..}} and {{{..}}}, but what do I know? My extremely quick attempt at resolving the issue didn't fix it.

Hi, whatever.jsonschema.js filename will generate an html file named whateveronschema.html. It looks like languages extensions are replaced everywhere in the filename. I had the version from pip. Regards.

Changelog

• Add Python 2.5 compatibility
• Add python2.5 compatible with_statement and format
• Add Python 2.5 compatibility
• Add python2.5 compatible with_statement and format
• Removes commented unnecessary code
• Adds charset and content type to css link
• Makes generated docs preserve source fileextension
• Minifies generated CSS using cssmin
• Removes reference to the pycco/resources.py file
• Removes pycco/resources.py
• Moves resources into separate editable files
• Updates console script to pycco/init.py
• Renames the main.py script to init.py
• Removes the pycco/init.py file
• Adds ignore rules to exclude buildout directories
• Adds zc.buildout configuration and bootstrap script
• Moves the pycco_resources package into a module
• Updates documentation for script entry-point
• Replaces relative wildcard import with explicit
• Adds MANIFEST.in to distribute additional files
• Cleans up setup.py
• Adds UTF-8 as encoding for Python source files
• Cleans up AUTHORS, README, and LICENSE
• Adds multiline comment delimiters for C and C++

How do I get an h3 header (f.e. the "Main Documentation Generation Functions" in http://fitzgen.github.com/pycco/)?

I'm writing Javascript and whenever I do: // === Yadda === I get an em instead of an h3.

This patch supports comments of the form:

/*
 * some comment
 * continues for a while
 *
 */

Specifically, it removes the "*" in the middle lines so they don't appear in the output as a markdown bulleted list.

This addresses issue 30 (https://github.com/fitzgen/pycco/issues/30)

This is a great project! I used it for a project documenting how to integrate Livefyre for our customers. It helped a lot!

I wanted to use it on an HTML document, though. So I added rudimentary HTML support for multiline comments. I couldn't do it with the built in symbol-only definition in the langs dict, so I added two lines to generate_html to let me explicitly define divider_text and divider_html.

You can see it in action here: http://demos.livefyre.com/ssosandbox/help/

I will probably have a need soon to add support for not needing to have a newline between the <!-- and the actual comment, but I think that will be more invasive. Someone might be able to tweak a regex somewhere to do it easily. I didn't grok the whole program, but like I said, it's great!

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

matth@lenovo 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 <module>
  File "C:\Users\matth\.virtualenvs\no_algo_twitter-Vk_lV-hQ\lib\site-packages\pycco\__init__.py", line 1, in <module>
    from .main import *  # noqa
  File "C:\Users\matth\.virtualenvs\no_algo_twitter-Vk_lV-hQ\lib\site-packages\pycco\main.py", line 60, in <module>
    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 <module>
    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 <module>
    import pystache
  File "C:\Users\matth\.virtualenvs\no_algo_twitter-Vk_lV-hQ\lib\site-packages\pystache\__init__.py", line 2, in <module>
    from init import *
ModuleNotFoundError: No module named 'init'

matth@lenovo 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.

Hi There,

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

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:

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.

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

Bumps pygments from 2.5.2 to 2.7.4.

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.

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.

#!/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 <module>
    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!