{"id":17801596,"url":"https://github.com/ryanfreckleton/doctress","last_synced_at":"2025-04-02T04:14:57.851Z","repository":{"id":151389836,"uuid":"90305008","full_name":"ryanfreckleton/doctress","owner":"ryanfreckleton","description":"A modern literate programming tool for python","archived":false,"fork":false,"pushed_at":"2017-05-05T21:53:49.000Z","size":46,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-07T18:53:49.265Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ryanfreckleton.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2017-05-04T20:07:29.000Z","updated_at":"2023-03-05T01:54:14.000Z","dependencies_parsed_at":null,"dependency_job_id":"b3295fdf-e4a8-4120-986a-9684b946f125","html_url":"https://github.com/ryanfreckleton/doctress","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/ryanfreckleton%2Fdoctress","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryanfreckleton%2Fdoctress/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryanfreckleton%2Fdoctress/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryanfreckleton%2Fdoctress/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ryanfreckleton","download_url":"https://codeload.github.com/ryanfreckleton/doctress/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246752635,"owners_count":20827987,"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":[],"created_at":"2024-10-27T12:38:59.301Z","updated_at":"2025-04-02T04:14:57.834Z","avatar_url":"https://github.com/ryanfreckleton.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"########\nDoctress\n########\n\n*Making documentation handsome.*\n*Mingle code and documentation*\n*Documentation for humans*\n*Low-carb documentation and presentations*\n*Beautiful documentation, organized code*\n\nInspired by the idio plugin of dexy, this is toolset built on RestructuredText\nto allow for a type of \"trap door\" literate programming and documentation.\nSource code is annotated with block names and end statements and can be\ninterspersed with prose, results of tests and metrics in a single document to\nbe rendered into HTML, LaTeX or other formats.\n\nUsage\n=====\n::\n\n    doctress \u003cinputfile\u003e [-o outfile]\n\nRun doctress on the rst file ``\u003cinputfile\u003e`` by default output goes on stdout,\nbut can be specified with ``-o``.\n\nInput file can also be set to ``-`` to read from ``stdin``.\n\nOptions\n-------\n\n::\n\n    doctress \u003cinputfile\u003e -t beamer [-o outfile]\n\nInstallation\n============\nRequirements\n------------\n\nFeatures\n========\n - Multi-lingual (Python, C, any source code)\n - Multiple outputs:\n\n   - LaTeX, ConTeXt (eventually), beamer, HTML\n\nThe code (in ``file.code``) is broken into blocks such that::\n\n    ### Block Name\n    Code goes here\n\nThen that's picked up by the directive::\n\n    .. see:: example.py Block Name\n\nThe filetype is guessed by the extension, but can be added with a :code:\noption after the directive. ``Block Name`` is found by looking for three\ncomment characters. I.e.::\n\n    ### python\n    /// C++\n    %%% MATLAB\n    ;;; lisp\n    --- Haskell\n\nTrailing comment characters are stripped as is white space, for example, the\nfollowing four statements are equivalent::\n\n    ### Block\n    ### Block ###\n    ###       Block ##\n    ###    Block     ########\n\nThis directive automatically dedents the code to flow nicely with the rest of\nthe document.\n\nIt may be useful in the future to automatically set tabstops and/or do\nsomething like `elastic tabstops`_.\n\n.. _elastic tabstops: http://nickgravgaard.com/elastic-tabstops/\n\nRequirements\n============\nCompatibility\n=============\nLicense\n=======\n\nQuestions\n=========\n - Why does this exist?\n\n    - To make it easier for me to do literate programming, make presentations\n      and keep a knowledge base of code.\n    - To have something fun to show people and something to make code analysis\n      more enjoyable. To give something to the software development community\n      that is beneficial.\n\n - Why should someone use this tool?\n\n   - Because it's simple, extensible, fast and makes beautiful output,\n     including integration of visualization, testing and metrics.\n   - It's fun! It allows you to analyze and explain things.\n\n - How can you add plugins and customize it for your own use?\n\n   - Custom output formats\n   - Custom directives\n   - Integrating with metrics\n   - Integrating with visualizations\n\n - How simple can we be?\n\n   - Use docutils extensively\n   - Steal from sphinx\n   - use doit when necessary\n   - Support both Python 2 and 3\n   - Look nice\n\nArchitecture\n============\nDoctress is built on top of docutils and doit. Docutils has a simple fundamental\narchitecture:\n\nDocutils\n--------\nParser\n    Custom directives and roles.\n\n    Directive class\n        Inline\n        TextElement\n\n        attributes: Argument detaiils\n        Option names\n        Whether it has content\n\n        self.assert_has_content()\n        self.content\n        self.arguments\n        self.final_argument_whitespace\n\n        Node children?\n\n    Node class\n\nTransform\n    Combining information from different nodes into a more appropriate tree.\nWriter\n    Translator?\n    Outputting to a specific format\n\ndoit\n----\ndoit is used to handle dependency management and running against multiple\nfiles. It'll also be how to integrate into other tools.\n\nPlugins\n-------\nNot sure about plugins yet. Definitely should be pip installable and easy to\nmake.\n\n- http://pluginbase.pocoo.org/\n- https://github.com/dexy/cashew\n- http://yapsy.sourceforge.net/\n- http://termie.pbworks.com/w/page/20571923/SprinklesPy\n- http://docs.openstack.org/developer/stevedore/patterns_loading.html\n- http://stackoverflow.com/questions/932069/building-a-minimal-plugin-architecture-in-python\n\nAuthors\n=======\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryanfreckleton%2Fdoctress","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fryanfreckleton%2Fdoctress","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryanfreckleton%2Fdoctress/lists"}