{"id":26650567,"url":"https://github.com/rochacbruno/markdocs","last_synced_at":"2025-03-25T02:01:44.307Z","repository":{"id":57439685,"uuid":"101001531","full_name":"rochacbruno-archive/markdocs","owner":"rochacbruno-archive","description":"Extract markdown from Python source file comments and outputs structured documentation \u0026 README file.","archived":false,"fork":false,"pushed_at":"2017-08-22T00:05:37.000Z","size":12,"stargazers_count":9,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-24T20:42:53.797Z","etag":null,"topics":["documentation","documentation-generator","documentation-tool","markdown","markdown-parser","markdown-parsing","python","python-documentation"],"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/rochacbruno-archive.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":"2017-08-21T23:48:01.000Z","updated_at":"2022-01-12T17:19:12.000Z","dependencies_parsed_at":"2022-09-26T17:20:43.594Z","dependency_job_id":null,"html_url":"https://github.com/rochacbruno-archive/markdocs","commit_stats":null,"previous_names":["rochacbruno/markdocs"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rochacbruno-archive%2Fmarkdocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rochacbruno-archive%2Fmarkdocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rochacbruno-archive%2Fmarkdocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rochacbruno-archive%2Fmarkdocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rochacbruno-archive","download_url":"https://codeload.github.com/rochacbruno-archive/markdocs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245383037,"owners_count":20606265,"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":["documentation","documentation-generator","documentation-tool","markdown","markdown-parser","markdown-parsing","python","python-documentation"],"created_at":"2025-03-25T02:01:43.368Z","updated_at":"2025-03-25T02:01:44.290Z","avatar_url":"https://github.com/rochacbruno-archive.png","language":"Python","readme":"# markdocs\nExtract markdown from Python source file comments and outputs structured documentation \u0026amp; README file.\n\n# Python documentation\n\nI'm enjoying writing functional documentation using __Markdown__ in __Rustlang__, so I'll do experiments to have the same functionality in Python.  Take a look at [rustdoc](https://doc.rust-lang.org/book/first-edition/documentation.html) and [here an example](https://doc.rust-lang.org/rand/rand/index.html) of documentation site generated for a Rust crate using [markdown comments](https://doc.rust-lang.org/rand/src/rand/lib.rs.html#11-1288).\n\nInformation is extracted using `python -m tokenize file.py` https://docs.python.org/3.5/library/tokenize.html#examples\n\n[Markdown](http://commonmark.org/help/)\n\n## How it works\n\n\u003e NOTE: this is just an early stage idea, not implemented yet! if you like please comment.\n\nThe _Markdocs_ extracts documentation from all _.py_ files and outputs in a well organized documentation _html_ site which can use the mkdocs.org to expose and deploy.\n\n```bash\nmarkdocs /path/to/project\n```\n\nIf you dont want to generate full documentation you can easily generate a readme file for your repo\n\n```bash\nmarkdocs /path/project --readme README.md -k 'filter-oly-some-files-and-objects'\n```\n\nWith the above a `README.md` is generated including only the filtered files and objects documentation, but you can also generate a single README for your whole project.\n\n\nAll `.py` files on that folder will be parsed for documentation blocks which are Python multiline comments starting in `!` example:\n\n\u003e NOTE: if you don't like mixing code and documentation, you can use a `mymodule.md` to document `mymodule.py` and the `.md` should be located in the same folder or in `mdocs` folder of the project. You can also write separated object files like in `mymodule.myclass.mymethod.md` which will be linked only to the `mymethod` of `MyClass`.\n\n```python\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```     \n \nAs you can see the `!!` can be also used, in fact you can use as many `!!!!!` 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 https://gist.github.com/rochacbruno/1689c849f3ef54086772c410d77a82de\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frochacbruno%2Fmarkdocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frochacbruno%2Fmarkdocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frochacbruno%2Fmarkdocs/lists"}