Metadata-Version: 2.4
Name: dycco
Version: 1.1.0
Summary: Literate-programming-style side-by-side documentation generator
Author-email: R J Ladyman <it@file-away.co.uk>
License-Expression: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: importlib-metadata==5.0.0
Requires-Dist: markdown>=2.4
Requires-Dist: pygments>=2.7.4
Requires-Dist: pystache>0.5.3
Requires-Dist: zipp==3.10.0
Dynamic: license-file

# Dycco

Dycco is a(nother) Python port of [Docco](https://ashkenas.com/docco/),
the original quick-and-dirty, hundred-line-long,
literate-programming-style documentation generator. For an example and
more information on Dycco, see [its self-generated
docs](https://rojalator.github.io/dycco/dycco.html).

Dycco was originally written by [Will McCutchen](mailto:will@mccutch.org)

Example output:-

> - <https://rojalator.github.io/session3/literate/session3/SessionManager.html>
> - <https://rojalator.github.io/pycco/main_py.html> (includes a diagram)
> - <https://rojalator.github.io/dycco/dycco.html>

This version allows output to a markdown file or to an asciidoc3 file,
as well as adding a option to sanitize internal HTML (which is handy if
your code includes html fragments). Dycco can generate documentation for
Python files and nothing else.

You can use [Pycco](https://github.com/pycco-docs/pycco) (or a
[new_version](https://github.com/rojalator/pycco)) instead, for other
types of file, that uses Dycco\'s code internally to handle Python
files.

## Installation

Use [pip](http://www.pip-installer.org/) or uv to install:

    pip install git+https://github.com/rojalator/dycco

## Usage

### Command Line Usage

Just pass `dycco` a list of files and it will generate documentation for
each of them. By default, the generated documentation is put in a
`docs/` subdirectory:

    $ dycco my_python_file.py

Dycco can generate docs for multiple files at once:

    $ dycco my_package/*.py

And you can control the output location:

    $ dycco --output-dir=/path/to/docs my_package/*.py

All command line options are given below:

    $ dycco --help

Outputs:

    usage: dycco [-h] [-o OUTPUT_DIR] [-a] [-e] [-f] source_file [source_file ...]

    Literate-style documentation generator.

    positional arguments:
      source_file           Source files to document

    optional arguments:
      -h, --help            show this help message and exit
      -o OUTPUT_DIR, --output-dir OUTPUT_DIR
                            Output directory (will be created if necessary)
      -a, --asciidoc3       Process with asciidoc3 instead of markdown (you will have to install asciidoc3, of course)
      -e, --escape-html     Run the documentation through html.escape() before markdown or asciidoc3
      -f, --single-file     Just produce a .md or .adoc file in single-column to be processed externally

### Library Usage

Dycco can also be used as a plain old Python library:

    >>> import dycco
    >>> dycco.document('my_python_file.py', 'my_output_dir')

## Credits

Dycco is just a simple re-implementation of
[Docco](https://ashkenas.com/docco/), with some inspiration and template
code from its primary Python port
[Pycco](https://github.com/pycco-docs/pycco) ([and an updated
version](https://github.com/rojalator/pycco))
