{ "info": { "author": "Miguel Grinberg", "author_email": "miguelgrinberg50@gmail.com", "bugtrack_url": null, "classifiers": [ "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Programming Language :: Python", "Programming Language :: Python :: 2", "Programming Language :: Python :: 3", "Topic :: Software Development :: Libraries", "Topic :: Software Development :: Libraries :: Python Modules" ], "description": "flatdoc\n=======\n\nFlatdoc is a simple tool that generates flat documentation from docstrings that\nare defined in modules, functions, classes and methods in your code.\n\nInstallation\n------------\n\nYou can install flatdoc with ``pip``::\n\n pip install flatdoc\n\nWriting Documentation\n---------------------\n\nYou can write your module, function, class and method documentation in any\nformat that you like. Markdown and reStructuredText are both good formats to\nuse, since they are easy to type, they are very readable, and have the tooling\nnecessary to generate HTML, PDF, Postscript, etc.\n\nThe key to build the flat documentation from all these docstrings is to link\nthem with the ``!INCLUDE`` directive. As an example, consider the following\nmodule foo.py, with Markdown docstrings::\n\n \"\"\"# Foo\n\n This module does foo.\n\n !INCLUDE Bar, func\n \"\"\"\n class Bar:\n \"\"\"## Bar\n\n This class does bar.\n\n !INCLUDE baz\n \"\"\"\n def baz(self):\n \"\"\"### baz()\n\n This method does baz.\n \"\"\"\n pass\n\n def func():\n \"\"\"## func()\n\n This function does func.\n \"\"\"\n pass\n \"\"\"\n\nThe generated documentation for the above module would be a consolidated\nMarkdown file::\n\n # Foo\n\n This module does foo.\n\n ## Bar\n\n This class does bar.\n\n ### baz()\n\n This method does baz.\n\n ## func()\n\n This function does func.\n\nThe !INCLUDE directive\n----------------------\n\nAs you've seen in the example in the previous section, documentation lines that\nbegin with ``!INCLUDE`` are treated as references to other docstrings. With\nthis mechanism multiple docstrings can be consolidated into a single output\ndocument.\n\nThe argument given to ``!INCLUDE`` is a comma-separated list of references to\nother docstrings. These references are always relative to the current\ndocstring, so for example, in a module docstring, any top-level functions or\nclasses can be referenced by their names, and in a class, all its methods can\nalso be referenced directly by their names.\n\nWhen there is a need to reference a docstring that is not a direct subordinate,\na standard dot notation can be used. Using the example of the previous section,\nconsider the following cases:\n\n- Include method ``baz`` of class ``Bar`` from module ``foo``::\n\n !INCLUDE Bar.baz\n\n- Include class ``Bar`` from function ``func``::\n\n !INCLUDE .Bar\n\n- Include a module ``mod`` that exists at the same level as ``foo`` from method\n ``baz``::\n\n !INCLUDE ...mod\n\nCommand Line Usage\n------------------\n\nThe ``flatdoc`` utility can be used to generate documentation from the\ncommand line. The only argument this command takes is the import name of\nthe top-level object to generate documentation for.\n\nThis documentation you are reading was generated with the following\ncommand::\n\n flatdoc flatdoc > README.rst\n\n\nAPI Reference\n-------------\n\n`flatdoc(name)`\n~~~~~~~~~~~~~~~\n\nGenerates documentation from docstrings.\n\nParameters\n^^^^^^^^^^\n\n======== ======== ===============\n Name Type Description\n======== ======== ===============\n `name` string The import name for the top-level object to document.\n======== ======== ===============\n\nReturn value\n^^^^^^^^^^^^\n\nA string with the flattened documentation.\n\nExample\n^^^^^^^\n\nThe following example generates the documentation for a package named\n``my_pkg`` and prints it to the console::\n\n from flatdoc import flatdoc\n print(flatdoc('my_pkg'))", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/miguelgrinberg/flatdoc", "keywords": null, "license": "MIT", "maintainer": null, "maintainer_email": null, "name": "flatdoc", "package_url": "https://pypi.org/project/flatdoc/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/flatdoc/", "project_urls": { "Download": "UNKNOWN", "Homepage": "https://github.com/miguelgrinberg/flatdoc" }, "release_url": "https://pypi.org/project/flatdoc/0.1.0/", "requires_dist": null, "requires_python": null, "summary": "Docstring flat documentation generator", "version": "0.1.0" }, "last_serial": 2080391, "releases": { "0.1.0": [ { "comment_text": "", "digests": { "md5": "20fe04734024a56205b41cfd7fc43f3c", "sha256": "7b63a75968dc6a56cea0e8b2f21afbef152418323607b8efc70432b5894fac2c" }, "downloads": -1, "filename": "flatdoc-0.1.0.tar.gz", "has_sig": false, "md5_digest": "20fe04734024a56205b41cfd7fc43f3c", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 4052, "upload_time": "2016-04-23T22:47:53", "url": "https://files.pythonhosted.org/packages/85/1b/1584b27428f824405425ab8b8a909ffca073f6131b7df0d77d9bf13ad9cd/flatdoc-0.1.0.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "20fe04734024a56205b41cfd7fc43f3c", "sha256": "7b63a75968dc6a56cea0e8b2f21afbef152418323607b8efc70432b5894fac2c" }, "downloads": -1, "filename": "flatdoc-0.1.0.tar.gz", "has_sig": false, "md5_digest": "20fe04734024a56205b41cfd7fc43f3c", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 4052, "upload_time": "2016-04-23T22:47:53", "url": "https://files.pythonhosted.org/packages/85/1b/1584b27428f824405425ab8b8a909ffca073f6131b7df0d77d9bf13ad9cd/flatdoc-0.1.0.tar.gz" } ] }