{ "info": { "author": "Bruno Rocha", "author_email": "rochacbruno@gmail.com", "bugtrack_url": null, "classifiers": [ "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Programming Language :: Python :: 3.6", "Topic :: Documentation", "Topic :: Software Development :: Documentation", "Topic :: Software Development :: Quality Assurance" ], "description": "markdocs\n========\n\nExtract markdown from Python source file comments and outputs structured\ndocumentation & README file.\n\nPython documentation\n--------------------\n\nI'm enjoying writing functional documentation using **Markdown** in\n**Rustlang**, so I'll do experiments to have the same functionality in\nPython. Take a look at\n`rustdoc `__\nand `here an example `__\nof documentation site generated for a Rust crate using `markdown\ncomments `__.\n\nInformation is extracted using ``python -m tokenize file.py``\nhttps://docs.python.org/3.5/library/tokenize.html#examples\n\n`Markdown `__\n\nHow it works\n------------\n\n NOTE: this is just an early stage idea, not implemented yet! if you\n like please comment.\n\nThe *Markdocs* extracts documentation from all *.py* files and outputs\nin a well organized documentation *html* site which can use the\nmkdocs.org to expose and deploy.\n\n.. code:: bash\n\n markdocs /path/to/project\n\nIf you dont want to generate full documentation you can easily generate\na readme file for your repo\n\n.. code:: bash\n\n markdocs /path/project --readme README.md -k 'filter-oly-some-files-and-objects'\n\nWith the above a ``README.md`` is generated including only the filtered\nfiles and objects documentation, but you can also generate a single\nREADME for your whole project.\n\nAll ``.py`` files on that folder will be parsed for documentation blocks\nwhich are Python multiline comments starting in ``!`` example:\n\n NOTE: if you don't like mixing code and documentation, you can use a\n ``mymodule.md`` to document ``mymodule.py`` and the ``.md`` should\n be located in the same folder or in ``mdocs`` folder of the project.\n You can also write separated object files like in\n ``mymodule.myclass.mymethod.md`` which will be linked only to the\n ``mymethod`` of ``MyClass``.\n\n.. code:: python\n\n \"\"\"!\n # this is a documentation written in markdown\n As it has only one `!` at the top, it is considered the module documentation\n I can include module documentation along the file and will be merged in to the top level documentation\n \"\"\"\n\n from foo import bar\n\n \"\"\"!!\n # This is an object documentation, can be used for any object but most for functions and classes\n It is defined before the object and not on the `__doc__` docstring, as markdocs does not conflicts with it.\n\n ## What are the advantages\n - Markdown is easy to learn\n - More people will contribute to documentation because they already know the format\n - With simple commands like `markdocs /path --readme README.md` the readme for your repo is generated from markdocs\n - Markdocs will generate the output for http://www.mkdocs.org/\n - You can write bare `.md` files in a `mdocs` folder and they will be added to you documentation as well\n\n [[params\n # X is the single param of this function\n x: int | default 0\n # The return is a string with the x interpolated.\n ]] result: str\n \"\"\"\n def a_function(x=0):\n \"\"\"This regular docstring does not conflicts with the above markdoc\"\"\"\n return f'Hello {x}'\n\n \"\"\"!!\n # This is a class documentation\n We can also define runnable and highlighted blocks of code.\n ```run\n obj = MyClass()\n ```\n \"\"\"\n class MyClass:\n \"\"\"the class docstring is not affected\"\"\"\n attr = 'foo'\n \"\"\"!!!\n # this is a method documentation\n [[params\n x: str\n ]]\n \"\"\"\n def method(self, x):\n \"\"\"This is the regular docstring for method\"\"\"\n a = x\n \"\"\"!!!!\n ## Here we increase the nesting level\n Markdown is amazing!\n \"\"\"\n def inner_function(..):\n pass\n\nAs you can see the ``!!`` can be also used, in fact you can use as many\n``!!!!!`` you want to define nesting.\n\nParser options are:\n\n- https://github.com/miyuchina/mistletoe/\n- https://github.com/lepture/mistune#lexers\n\nWebsite output formats\n\n- mkdocs.org\n- https://github.com/rocadocs/rocadocs\n\nmore on\nhttps://gist.github.com/rochacbruno/1689c849f3ef54086772c410d77a82de\n", "description_content_type": null, "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/rochacbruno/markdocs", "keywords": "", "license": "", "maintainer": "rochacbruno", "maintainer_email": "rochacbruno@gmail.com", "name": "markdocs", "package_url": "https://pypi.org/project/markdocs/", "platform": "", "project_url": "https://pypi.org/project/markdocs/", "project_urls": { "Homepage": "https://github.com/rochacbruno/markdocs" }, "release_url": "https://pypi.org/project/markdocs/0.0.0/", "requires_dist": [ "mistune" ], "requires_python": ">=3.6", "summary": "Markdocs - Python documentation using markdown", "version": "0.0.0" }, "last_serial": 3115109, "releases": { "0.0.0": [ { "comment_text": "", "digests": { "md5": "063972f6e1c17cc8c7beb2b20302478c", "sha256": "64fda59814e39cb096cfbb3572694dd17445a0039d0fcce3e486e2190d72e68a" }, "downloads": -1, "filename": "markdocs-0.0.0-py3-none-any.whl", "has_sig": false, "md5_digest": "063972f6e1c17cc8c7beb2b20302478c", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=3.6", "size": 4976, "upload_time": "2017-08-22T16:12:24", "url": "https://files.pythonhosted.org/packages/35/9e/8f70a52c4516b7e20f5ef14d61e2440d8cb248bf748ec08cb5c200839c4a/markdocs-0.0.0-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "1119bdc6fc7809ef9826f9adc1ec0b44", "sha256": "8c23f6f77a33d34ad24fe7ed3964cb0701cfbc6185961f680ce55b837de4fbe8" }, "downloads": -1, "filename": "markdocs-0.0.0.tar.gz", "has_sig": false, "md5_digest": "1119bdc6fc7809ef9826f9adc1ec0b44", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.6", "size": 5678, "upload_time": "2017-08-22T16:12:26", "url": "https://files.pythonhosted.org/packages/4b/9b/9246911cf2d1c06718e3c56149cea8cdad7f42f05d314bc90190d7dfbc59/markdocs-0.0.0.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "063972f6e1c17cc8c7beb2b20302478c", "sha256": "64fda59814e39cb096cfbb3572694dd17445a0039d0fcce3e486e2190d72e68a" }, "downloads": -1, "filename": "markdocs-0.0.0-py3-none-any.whl", "has_sig": false, "md5_digest": "063972f6e1c17cc8c7beb2b20302478c", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=3.6", "size": 4976, "upload_time": "2017-08-22T16:12:24", "url": "https://files.pythonhosted.org/packages/35/9e/8f70a52c4516b7e20f5ef14d61e2440d8cb248bf748ec08cb5c200839c4a/markdocs-0.0.0-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "1119bdc6fc7809ef9826f9adc1ec0b44", "sha256": "8c23f6f77a33d34ad24fe7ed3964cb0701cfbc6185961f680ce55b837de4fbe8" }, "downloads": -1, "filename": "markdocs-0.0.0.tar.gz", "has_sig": false, "md5_digest": "1119bdc6fc7809ef9826f9adc1ec0b44", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.6", "size": 5678, "upload_time": "2017-08-22T16:12:26", "url": "https://files.pythonhosted.org/packages/4b/9b/9246911cf2d1c06718e3c56149cea8cdad7f42f05d314bc90190d7dfbc59/markdocs-0.0.0.tar.gz" } ] }