Skip to content

Latest commit

 

History

History
79 lines (51 loc) · 5.63 KB

CONTRIBUTING.md

File metadata and controls

79 lines (51 loc) · 5.63 KB
Raw

Contributing to Panflute

👍🎉 First off, thanks for taking the time to contribute! 🎉👍

This document contains useful resources and guidelines when contributing to the project:

Table Of Contents

Style Guide

For consistency, code should try to comply (as much as possible) with pep8, and with the style guides by @kennethreitz and Google.

flake8

flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics

Useful tools

  • pycodestyle (formerly pep8): run it with pycodestyle ./panflute > pycodestyle-report.txt
  • pylint: run it with pylint panflute > pylint-report.txt from the root folder of the repo
  • Github Actions. CI tool that run automatically after pushing code. Amongst other things, it runs pytest on all the test_*.py files in the \tests folder.

Panflute internals

Program flow

  • Filters usually call panflute with panflute.run_filter(action).
    • Note: run_filter, toJSONFilter and toJSONFilters are just thin wrappers for run_filters.
  • Within run_filter,
    1. doc = panflute.load() reads the JSON input from stdin and creates a panflute.Doc object, which is just a tree containing the entire document.
    2. doc.walk(action, doc) will walk through the document tree (top to bottom) and apply the action function
    3. panflute.dump(doc) will encode the tree into JSON and dump it to stdout, finishing execution

Modules in the panflute package

  • __init__.py: loads the functions that will be part of API of the package.
  • utils.py: contains auxiliary functions that do not depend on any other part of panflute.
  • version.py: has the version string.
  • containers.py: has a ListContainer and DictContainer classes. These are just wrappers around lists and dicts, that i) allow only certain items of certain types to be added (through .oktypes), and ii) keep track of the parent objects to allow for navigation through the tree (so you can do .parent, .prev, .next, etc.).
    • Note: there is also a rarely used ._container property, needed for when the parent object can hold more than one container. For instance, Doc holds both standard items in .content and also metadata items in .metadata, so in order to traverse the tree, we need to know in what container of the parent each item is. This is only used by the Doc, Citation, DefinitionItem, Quoted and Table objects.
  • base.py: has the base classes of all Pandoc elements. These are Element and its subclasses Block, Inline and Metadata.
  • elements.py: have all the standard Pandoc elements (Str, Para, Space, etc.). Pandoc elements inherit from one of three base classes (Block, Inline and Metadata), which we use to make sure that an elements does not get placed in another element where it's not allowed.
    • Note: there are some elements not present in pandoc-types that are subclass from Element directly. These are Doc, Citation, ListItem, Definition, DefinitionItem, TableCell and TableRow. This allow filters to be applied directly to table rows instead of to tables and then looping within each item of the table.
    • elements.py also contains the function from_json, which is essential in converting JSON elements into Pandoc elements.
  • io.py: holds all the I/O functions (load, dump, run_filters, and wrappers).
  • tools.py: contain functions that are useful when writing filters (but not essential). These include stringify, yaml_filter, convert_string, etc.
    • Note: future enhancements to panflute should probably go here.
  • autofilter.py: has the code that allows panflute to be run as an executable script.
    • This allows panflute to be run as a filter (!), in which case it uses the panflute-... metadata to conveniently call different filters.

Documentation

Panflute uses Sphinx for its documentation. To install it, install Python 3.3+ and then run pip install sphinx (or see here).

To build the documentation, navigate to the /docs folder and type make html. The build files will then be placed in /docs/build/html, and can be copied into a website

The guides are written in REST and located in the /docs/source folder.

The API docs are written as comments in the source code itself (so e.g. this is autogenerated).

REST guides