{"id":27557310,"url":"https://github.com/gaspect/pylliterate","last_synced_at":"2025-10-18T21:48:32.619Z","repository":{"id":235915479,"uuid":"791535086","full_name":"gaspect/pylliterate","owner":"gaspect","description":"Unobtrusive literate programming experience for Python pragmatists","archived":false,"fork":false,"pushed_at":"2024-10-01T00:23:49.000Z","size":1017,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-16T11:39:01.457Z","etag":null,"topics":["documentation","documentation-tool","python"],"latest_commit_sha":null,"homepage":"https://gaspect.github.io/pylliterate/","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/gaspect.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-24T22:23:13.000Z","updated_at":"2024-10-01T00:17:42.000Z","dependencies_parsed_at":"2024-04-30T05:54:18.185Z","dependency_job_id":null,"html_url":"https://github.com/gaspect/pylliterate","commit_stats":null,"previous_names":["gaspect/pylliterate"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaspect%2Fpylliterate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaspect%2Fpylliterate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaspect%2Fpylliterate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaspect%2Fpylliterate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gaspect","download_url":"https://codeload.github.com/gaspect/pylliterate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249794464,"owners_count":21326719,"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-tool","python"],"created_at":"2025-04-19T20:29:20.949Z","updated_at":"2025-10-18T21:48:27.566Z","avatar_url":"https://github.com/gaspect.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pylliterate: python illiterate programing\n\n[\u003cimg alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/pylliterate\"\u003e](https://pypi.org/project/pylliterate)\n[\u003cimg alt=\"PyPI - License\" src=\"https://img.shields.io/pypi/l/pylliterate\"\u003e](https://github.com/gaspect/pylliterate)\n[\u003cimg alt=\"PyPI - Python Version\" src=\"https://img.shields.io/pypi/pyversions/pylliterate\"\u003e](https://pypi.org/project/pylliterate)\n[\u003cimg alt=\"GitHub Repo stars\" src=\"https://img.shields.io/github/stars/gaspect/pylliterate?style=social\"\u003e](https://github.com/gaspect/pylliterate/stargazers)\n[\u003cimg alt=\"GitHub forks\" src=\"https://img.shields.io/github/forks/gaspect/pylliterate?style=social\"\u003e](https://github.com/gaspect/pylliterate/network/members)\n\n\u003e Unobtrusive literate programming experience for Python pragmatists\n\n`pylliterate` is a Python module that helps you apply _some_ of the literate programming paradigm\nwithout requiring a meta-programming language (like `noweb`) or any preprocessing step to actually\nget your code up and running.\n\nIt works kind of opposite to how literate programming suggests, in the sense that you write code-first\nand embed documentation into your code. I know, purist literate programmers will hate this but hey, it's a compromise.\n\n## What is all this (python il-literate)pyliterate programming about?\n\nIf you've never heard about literate programming before, then I suggest you to read at least the \n[Wikipedia entry](https://en.wikipedia.org/wiki/Literate_programming)\nand then we can continue discussing. \nIt is a fascinating topic, and there are [many resources](http://www.literateprogramming.com) out there.\n\nBack already? Ok, so here is pylliterate's take on this matter.\n\nIdeally, for literate programming to work, you would code in a meta-language mixing prose, code, and macros.\nThis is great if everyone that will ever write code in your project is willing to indulge in literate programming.\nSadly, I have found that more often that not, this is not the case.\nHence, even though it is awesome, literate programming has some major practical drawbacks that, at this moment,\nmake it impossible for many people to apply it widely, including:\n\n- Poor support from editors and lack of tooling, which is not just a matter of syntax highlighting. The very feature that makes\nliterate programming extra powerful, i.e., macros, makes it almost impossible for any semantic analysis to work, so forget\nabout intellisense, smart completion, or interactive linting.\n- A hard entry curve, since unfortunately people in the 21st century still learns to code the \"old\" way, that is,\ncode-first. Introducing someone into literate programming is hard because it takes some time to grok it and understand the benefits.\n- It's hard to incrementally switch to it. If you already have a somewhat large program written in the \"traditional\" way,\nit's very hard to port it to the literate programming paradigm incrementally. \n\nAll these reasons make it, at least for me, almost impossible to apply pure literate programming in anything more\nthan toy projects. However, I do love the paradigm, and I do think it makes you a better programmer, and makes your code\neasier to maintain and understand. I wanted a way to introduce as much of literate programming as possible into the\ntraditional programming paradigms, but still being able to use the same tools, introducing literate programming\nidiosyncrasies incrementally into existing\ncodebases but \"flying under the radar\" as much as possible, so detractors don't complain.\n\nHence, `pylliterate` was born. It is called that way in part because is kind of a twist on the literate programming\nparadigm, and also because it is supposed to help us illiterates to write more literate code.\n\n## So what does pylliterate propose?\n\nGlad you asked. The idea is to encourage a more literate codebase while introducing as few changes as possible.\nSpecifically, you should not need to use new tools, editor extensions, or preprocessors. Code written using the \npylliterate style looks exactly like regular code, but hopefully, a bit better.\n\nEverything stems from these key principles:\n\n- Documentation for a codebase should be written as prose, and it should be enjoyable to read it top to bottom. \nIt should not be simply a list of modules and methods with few-line descriptions; rather, it should be a cohesive\npiece of literature that clearly explains the authors' intents for any small details and how everything fits into the bigger\npicture.\n- Documentation should be as close as possible to real code, ideally right next to it, instead of in external \nmarkdown files that can easily get out of sync. Furthermore, there should be some automated way\nto ensure that documentation is up to date, ideally with embedded unit tests that fail if documentation is wrong.\n- Documentation should be written both for users of your code and future developers, and it should be\neasy for anyone to dive as deep as they want. This means that users only interested in calling your high-level\nAPI can easily understand how to use it, while collaborators or anyone wanting to understand how everything works\nshould also be able to follow all the details.\n\nTo achieve these objectives, pylliterate proposes really only one major paradigm shift:\n\n\u003e **Your code is the documentation.**\n\nThat's it. You will simply write all the documentation for your code right inside your code, as comments and as Python docstrings,\naccording that what is more convenient for each case. But keep this in mind, *all your code will be published as-is for documentation purposes*.\n\nNow you are forced to think about your code in terms of: \"well, this will be read by users at some point, so I better make it as publishable as possible\".\nThis means that you can no longer simply put some throw-away code in some forsaken `_tmp.py` file. That file will appear in the documentation, so it better be publishable.\n\n## How this works?\n\nThe only thing that pylliterate does is taking your Python repository and turn it into Markdown files.\nIt will parse all your code, and output nicely formatted Markdown versions of each `.py` file. It is up to you that what is writen in those `.py` files is something worth publishing as documentation.\n\nTo use it, you simply run:\n\n    python -m pylliterate build --src input:output --src .....\n\nWhere `input` is a folder or file holding your project's code (i.e., the top-level folder with an `__init__.py` inside), and `output` is where you want the markdown files. You can add  the `--src` argument as many times as needed even for copy verbatim files.\n\nI can do this for copying the `Readme.md` into an `index.md` which becomes the homepage.\n    \n    python -m pylliterate build --src Readme.md:docs/index.md\n\nFor example, in this project, standing on the root folder (where this Readme is located), you would run the following (🤓 yeah, it is kind if Inception-ish):\n\n    python -m pylliterate --src pylliterate:docs --src Readme.md/index.md\n\nThis will take all the code in `pylliterate`, convert it to Markdown, and drop it inside the `docs` folder.\nIt will also copy the `Readme.md` file into `docs/index.md`.\n\n### A tweak using settings.\n\nThe same procedure can be obtained using configuration files. The configuration files have the following structure:\n\n```yml\ninline: true # true if we want to process the comments within code blocks\nsources: # List of files to be processed or copied\n  python_package/sample_input.py: sample_docs_folder/sample_input.md  # input:output pair as in command line use case\n```\n\nThe configuration is usually in a file called **pylliterate.yml** somehow mimicking mkdocs.\n\nYou can mix pylliterate with regular markdown simply by hand-crafting all the documentation you want in pure Markdown and then conveniently designing your `mkdocs.yml`.\nYou can also see the `mkdocs.yml` in this repository to get an idea of how that configuration looks, but beware, I'm using some custom\nthemes and other stuff you might or might not want.\n\n## Next steps\n\nThis project is quite small, but it is a self-fulfilling prophecy. The remaining [documentation](https://gaspect.github.io/pylliterate) has been written with `pylliterate`. Just keep reading, and you'll see for yourself what does this mean.\n\n\n\u003e Disclaimer: This code is a copy **with improvements** of the original [illiterate](https://github.com/apiad/illiterate) project because was discontinued since 2022.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaspect%2Fpylliterate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgaspect%2Fpylliterate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaspect%2Fpylliterate/lists"}