Metadata-Version: 2.1
Name: npdoc2md
Version: 0.0.1
Summary: Scripts for autogenerating markdown docs from numpy-style docstrings.
Home-page: https://github.com/jwlodek/npdoc2md
Author: Jakub Wlodek
Author-email: jwlodek.dev@gmail.com
License: MIT
Description: # npdoc2md
        
        A simple python utility for auto-converting numpy-style python docstrings to 
        markdown for use with mkdocs, an entire package at a time. It also includes a second utility, `code2npdoc`, which will attempt to generate docstring templates given code for an entire project.
        
        ### Installation
        
        The preferred method for installing npdoc2md is to use `pip`. (Python 3.5+ required)
        
        ```
        pip install npdoc2md
        ```
        
        If `pip` defaults to Python2, use `pip3`. You can also install from source:
        
        ```
        git clone https://github.com/jwlodek/npdoc2md
        cd npdoc2md
        pip install .
        ```
        
        ### Usage
        
        Below is the result of running `npdoc2md` with the `-h` flag:
        
        ```
        usage: npdoc2md [-h] [-v] -i INPUT -o OUTPUT [-s SKIP [SKIP ...]] [-d]
        
        optional arguments:
          -h, --help            show this help message and exit
          -v, --version         Use this flag to print out npdoc2md version info.
          -i INPUT, --input INPUT
                                The path to the target python project or file to
                                convert.
          -o OUTPUT, --output OUTPUT
                                The output directory where the markdown files should
                                be placed.
          -s SKIP [SKIP ...], --skip SKIP [SKIP ...]
                                List of filenames/directories to skip.
          -d, --debug           Add this flag to print detailed log messages during
                                conversion.
        ```
        
        Basic usage will require at least target and output locations that are valid.
        
        ```
        npdoc2md -i C:\Users\jwlodek\demo -o C:\Users\jwlodek\demo_output
        ```
        
        You can also specify to enable debug printing with `-d`, and files to skip with `-s` followed by a list of files. For example, to autogenerate [py_cui](https://github.com/jwlodek/py_cui) docs, the following command is run:
        
        ```
        npdoc2md -i ..\..\..\py_cui -o ..\..\DocstringGenerated -s statusbar.py errors.py
        ```
        
        which will ignore the `statusbar.py` and `errors.py` files.
        
        The `npdoc2md` script will recursively search the target (if it is a folder) for files ending with the `.py` extension,
        and will generate a markdown file for each one not specified in the ignore section. Any encountered `__init__.py` files will use their containing folder's name for the name of the output markdown file.
        
        ### Doc Rules
        
        You must follow strict docstring style rules to use npdoc2md:
        
        * Each class of function docstring must start and end with `"""`, and the initial description must be right after the initial `"""`. Ex: `"""Hello this is a function`
        * Use numpy style guidelines for `Attributes`, `Parameters`, `Returns`, `Raises` lists
        * The `Returns` list should give a return value name and type with the doc message. If it doesn't, a generic name will be assigned to the return variable
        
        ### Examples
        
        As stated previously, [py_cui](https://github.com/jwlodek/py_cui) uses npdoc2md to auto-generate documentation to use with `mkdocs`.
        You may also see the `Npdoc2md.md` file in this repository which was generated by running this script on itself:
        
        ```
        npdoc2md -i .\npdoc2md.py -o .\example\.
        ```
        
        ### Generating template docs
        
        Writing out all of the docstrings for a project is a lengthy process, so a second helper script was written to help with generating template np docs. It has the following usage:
        
        ```
        usage: code2npdoc [-h] [-v] -i INPUT [-c] [-s SKIP [SKIP ...]] [-d]
        
        A utility for auto-creating base numpy style docstrings for an entire python
        project.
        
        optional arguments:
          -h, --help            show this help message and exit
          -v, --version         Add this flag for displaying version information.
          -i INPUT, --input INPUT
                                Path to target python project or file
          -c, --createtemp      If this flag is set, code2npdoc will create a
                                temporary conversion folder without overriding your
                                sources.
          -s SKIP [SKIP ...], --skip SKIP [SKIP ...]
                                List of filenames/directories to skip.
          -d, --debug           Add this flag to print detailed log messages during
                                conversion.
        ```
        
        With similar flags as the base `npdoc2md` script. Add the `-c` flag if you don't want your original file to be auto-overwritten. An example of running this script on the `npdoc2md` file is as follows:
        
        ```
        code2npdoc -i npdoc2md.py -c
        ```
        
        ### License
        
        MIT License  
        Copyright (c) 2020, Jakub Wlodek
        
Keywords: markdown numpy docs autogenerate script
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Python: >=3.5
Description-Content-Type: text/markdown
