{"id":15020441,"url":"https://github.com/jwlodek/npdoc2md","last_synced_at":"2025-10-26T00:31:13.537Z","repository":{"id":50151793,"uuid":"238783202","full_name":"jwlodek/npdoc2md","owner":"jwlodek","description":"A script for auto-converting numpy-style documentation to markdown for an entire python project","archived":false,"fork":false,"pushed_at":"2021-06-02T12:32:29.000Z","size":103,"stargazers_count":4,"open_issues_count":4,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-31T12:51:24.948Z","etag":null,"topics":["converter","docs","docstring-documentation","docstrings","markdown","numpy","script"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jwlodek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-02-06T20:57:21.000Z","updated_at":"2021-08-22T11:43:52.000Z","dependencies_parsed_at":"2022-09-07T05:51:25.567Z","dependency_job_id":null,"html_url":"https://github.com/jwlodek/npdoc2md","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwlodek%2Fnpdoc2md","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwlodek%2Fnpdoc2md/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwlodek%2Fnpdoc2md/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwlodek%2Fnpdoc2md/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jwlodek","download_url":"https://codeload.github.com/jwlodek/npdoc2md/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238235622,"owners_count":19438725,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["converter","docs","docstring-documentation","docstrings","markdown","numpy","script"],"created_at":"2024-09-24T19:55:05.655Z","updated_at":"2025-10-26T00:31:08.237Z","avatar_url":"https://github.com/jwlodek.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# npdoc2md\n\nA simple python utility for auto-converting numpy-style python docstrings to \nmarkdown 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.\n\n### Installation\n\nThe preferred method for installing npdoc2md is to use `pip`. (Python 3.5+ required)\n\n```\npip install npdoc2md\n```\n\nIf `pip` defaults to Python2, use `pip3`. You can also install from source:\n\n```\ngit clone https://github.com/jwlodek/npdoc2md\ncd npdoc2md\npip install .\n```\n\n### Usage\n\nBelow is the result of running `npdoc2md` with the `-h` flag:\n\n```\nusage: npdoc2md [-h] [-v] -i INPUT -o OUTPUT [-s SKIP [SKIP ...]] [-d]\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -v, --version         Use this flag to print out npdoc2md version info.\n  -i INPUT, --input INPUT\n                        The path to the target python project or file to\n                        convert.\n  -o OUTPUT, --output OUTPUT\n                        The output directory where the markdown files should\n                        be placed.\n  -s SKIP [SKIP ...], --skip SKIP [SKIP ...]\n                        List of filenames/directories to skip.\n  -d, --debug           Add this flag to print detailed log messages during\n                        conversion.\n```\n\nBasic usage will require at least target and output locations that are valid.\n\n```\nnpdoc2md -i C:\\Users\\jwlodek\\demo -o C:\\Users\\jwlodek\\demo_output\n```\n\nYou 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:\n\n```\nnpdoc2md -i ..\\..\\..\\py_cui -o ..\\..\\DocstringGenerated -s statusbar.py errors.py\n```\n\nwhich will ignore the `statusbar.py` and `errors.py` files.\n\nThe `npdoc2md` script will recursively search the target (if it is a folder) for files ending with the `.py` extension,\nand 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.\n\n### Doc Rules\n\nYou must follow strict docstring style rules to use npdoc2md:\n\n* 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`\n* Use numpy style guidelines for `Attributes`, `Parameters`, `Returns`, `Raises` lists\n* 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\n\n### Examples\n\nAs stated previously, [py_cui](https://github.com/jwlodek/py_cui) uses npdoc2md to auto-generate documentation to use with `mkdocs`.\nYou may also see the `Npdoc2md.md` file in this repository which was generated by running this script on itself:\n\n```\nnpdoc2md -i .\\npdoc2md.py -o .\\example\\.\n```\n\n### Generating template docs\n\nWriting 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:\n\n```\nusage: code2npdoc [-h] [-v] -i INPUT [-c] [-s SKIP [SKIP ...]] [-d]\n\nA utility for auto-creating base numpy style docstrings for an entire python\nproject.\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -v, --version         Add this flag for displaying version information.\n  -i INPUT, --input INPUT\n                        Path to target python project or file\n  -c, --createtemp      If this flag is set, code2npdoc will create a\n                        temporary conversion folder without overriding your\n                        sources.\n  -s SKIP [SKIP ...], --skip SKIP [SKIP ...]\n                        List of filenames/directories to skip.\n  -d, --debug           Add this flag to print detailed log messages during\n                        conversion.\n```\n\nWith 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:\n\n```\ncode2npdoc -i npdoc2md.py -c\n```\n\n### License\n\nMIT License  \nCopyright (c) 2020, Jakub Wlodek\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjwlodek%2Fnpdoc2md","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjwlodek%2Fnpdoc2md","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjwlodek%2Fnpdoc2md/lists"}