Improving Docs
richardscollin opened this issue · 3 comments
Hi! I started using this library for a project and I've been having a few difficulties because the docs are a bit sparse.
Would you accept a patch if I go to the effort of adding some?
In particular I want to improve the docs that are generated for:
FUNCTIONS
BlockQuote = fun(*args)
BulletList = fun(*args)
Cite = fun(*args)
Code = fun(*args)
CodeBlock = fun(*args)
DefinitionList = fun(*args)
Div = fun(*args)
Emph = fun(*args)
Header = fun(*args)
HorizontalRule = fun(*args)
Image = fun(*args)
... etc
I'll consult the haskell docs here to try to infer the right types. It will probably need a thorough review though as I'm not that familiar with the library.
As for implementing it I'm thinking of adding / changing some parameters to the elt function and have that update the docstring appropriately.
Best,
Collin
Oh, I just noticed you left #20 open inviting people to improve the docs. I'll go ahead and get started. I'll send a PR later this week.
Note that I recently become the maintainer of this repo. I plan on improving the doc (but not full blown documentation, as the pandoc AST is never really documented, and replies on people either going to the source or look at the JSON and guess.)
Another thing worth mentioning is, panflute is the recommended (both by the author and me) library to write pandoc filters in Python. If you want runtime type-checking, panflute has already implements all that.
Lastly, I intend to keep pandocfilters as mostly purely functional, and panflute will be the recommended object oriented interface to go. So beware that while it might be tempting to start adding classes to improve something here, it may diverge from the existing stable API (for 7+ years already) too much and not accepted. It is totally up to discussion though, as I'm still trying to figure out the right way to maintain this forward. So in order to save time, you might want to discuss what you want to improve first before implementing it.