GithubHelp home page GithubHelp logo

creisle / markdown_refdocs Goto Github PK

View Code? Open in Web Editor NEW
4.0 4.0 0.0 1.96 MB

Generate reference documentation from python package in markdown

Home Page: https://creisle.github.io/markdown_refdocs

License: MIT License

Python 100.00%
documentation-tool markdown python reference

markdown_refdocs's People

Contributors

areisle avatar creisle avatar

Stargazers

 avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

markdown_refdocs's Issues

Examples is ending up inside `Returns`

the followning docstring

'''
Split the input text into a prefix and suffix, according to the following patterns:

If the input string is letters followed by numbers, return them separately in a tuple.
If the input string is only letters, return a tuple of ({letters}, None).
If the input string is only numbers, return a tuple of (None, {numbers}).

Otherwise return a tuple of Nones.

Args:
    text (str): the input to split.

Returns:
    tuple: The result of splitting the input string.

Examples:
    prefix_split('A12345') == ('A', '12345')
    prefix_split('HTMCP_1') == ('HTMCP_', '1')

    prefix_split('ABC') == ('ABC', None)
    prefix_split('12345') == (None, '12345')

    prefix_split('A123B') == (None, None)
'''

renders like so
image

doesn't pick up all of docstring

it seems like it's only picking up the first line of a docstring

for this docstring

    '''
    Split the input text into a prefix and suffix, according to the following patterns:
    If the input string is letters followed by numbers, return them separately in a tuple.
    If the input string is only letters, return a tuple of ({letters}, None).
    If the input string is only numbers, return a tuple of (None, {numbers}).
    Otherwise return a tuple of Nones.
    Args:
        text (str): the input to split.
    Returns:
        tuple: The result of splitting the input string.
    Examples:
        prefix_split('A12345') == ('A', '12345')
        prefix_split('HTMCP_1') == ('HTMCP_', '1')
        prefix_split('ABC') == ('ABC', None)
        prefix_split('12345') == (None, '12345')
        prefix_split('A123B') == (None, None)
    '''

it generated the following

## prefix\_split()
Split the input text into a prefix and suffix, according to the following patterns:
```python
def prefix_split(text):

breaks for multiple decorator

I tried running this on a file that had a function with mulitple decorators and encountered the following error

Traceback (most recent call last):
  File "/home/areisle/bitbucket/pylims-api/server/venv3.7/bin/markdown_refdocs", line 8, in <module>
    sys.exit(command_interface())
  File "/home/areisle/bitbucket/pylims-api/server/venv3.7/lib/python3.7/site-packages/markdown_refdocs/main.py", line 484, in command_interface
    namespace_headers=args.namespace_headers,
  File "/home/areisle/bitbucket/pylims-api/server/venv3.7/lib/python3.7/site-packages/markdown_refdocs/main.py", line 418, in extract_to_markdown
    namespace_headers=namespace_headers,
  File "/home/areisle/bitbucket/pylims-api/server/venv3.7/lib/python3.7/site-packages/markdown_refdocs/main.py", line 381, in parse_module_file
    content = analyzer.visit(tree)
  File "/gsc/software/linux-x86_64-centos7/python-3.7.2/lib/python3.7/ast.py", line 262, in visit
    return visitor(node)
  File "/home/areisle/bitbucket/pylims-api/server/venv3.7/lib/python3.7/site-packages/markdown_refdocs/main.py", line 248, in visit_Module
    subnode = self.visit(elem)
  File "/gsc/software/linux-x86_64-centos7/python-3.7.2/lib/python3.7/ast.py", line 262, in visit
    return visitor(node)
  File "/home/areisle/bitbucket/pylims-api/server/venv3.7/lib/python3.7/site-packages/markdown_refdocs/main.py", line 145, in visit_FunctionDef
    decorators = {self.visit(d) for d in node.decorator_list}
  File "/home/areisle/bitbucket/pylims-api/server/venv3.7/lib/python3.7/site-packages/markdown_refdocs/main.py", line 145, in <setcomp>
    decorators = {self.visit(d) for d in node.decorator_list}
TypeError: unhashable type: 'list'

the decorators in question are from pyramid

from pyramid.view import (
    view_config,
)
from pyramid.security import (
    NO_PERMISSION_REQUIRED
)

@view_config(route_name='swagger', renderer='lims:templates/swagger.mak', permission=NO_PERMISSION_REQUIRED)
@view_config(route_name='swagger.json', renderer='json', permission=NO_PERMISSION_REQUIRED)
def swagger(request):
     # does stuff here

Error generating reference docs for MAVIS

Encountered this error generating reference docs from the mavis package

Traceback (most recent call last):
  File "/Users/creisle/git/markdown_refdocs/venv/bin/markdown_refdocs", line 11, in <module>
    load_entry_point('markdown-refdocs', 'console_scripts', 'markdown_refdocs')()
  File "/Users/creisle/git/markdown_refdocs/markdown_refdocs/main.py", line 508, in command_interface
    namespace_headers=args.namespace_headers,
  File "/Users/creisle/git/markdown_refdocs/markdown_refdocs/main.py", line 461, in extract_to_markdown
    fh.write(module_to_markdown(parsed, relative_mapping))
  File "/Users/creisle/git/markdown_refdocs/markdown_refdocs/markdown.py", line 175, in module_to_markdown
    md.append(class_to_markdown(cls, types_links=types_links))
  File "/Users/creisle/git/markdown_refdocs/markdown_refdocs/markdown.py", line 127, in class_to_markdown
    + ' '.join([create_type_link(t, types_links) for t in parsed['inherits']]),
  File "/Users/creisle/git/markdown_refdocs/markdown_refdocs/markdown.py", line 127, in <listcomp>
    + ' '.join([create_type_link(t, types_links) for t in parsed['inherits']]),
  File "/Users/creisle/git/markdown_refdocs/markdown_refdocs/markdown.py", line 44, in create_type_link
    type_link, has_link = _create_type_link(type_name, types_links)
  File "/Users/creisle/git/markdown_refdocs/markdown_refdocs/markdown.py", line 9, in _create_type_link
    m = re.match(r'^Optional\[(.*)\]$', type_name)
  File "/Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/Versions/3.7/lib/python3.7/re.py", line 173, in match
    return _compile(pattern, flags).match(string)
TypeError: expected string or bytes-like object

add admonitions for `Todo`s

it would be nice if Todo sections in docstrings where put into an admonition of some kind rather than ending up in the main description

for example, the following docstring:

"""
    validator for pk_select endpoint
    Todo:
        * validate pk_col exists on table
        * validate group_by is a column/list of columns on table
        * validate filter_col exists on table
        * validate dist_table joins to table?
    """

end up like so:
image

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.