{"id":16388038,"url":"https://github.com/dotmpe/docutils-ext","last_synced_at":"2026-06-06T23:30:15.753Z","repository":{"id":1308149,"uuid":"1250667","full_name":"dotmpe/docutils-ext","owner":"dotmpe","description":".mpe extensions for Python Docutils and reStructuredText","archived":false,"fork":false,"pushed_at":"2018-06-17T17:30:50.000Z","size":1314,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"dev","last_synced_at":"2025-01-03T09:47:07.098Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://dotmpe.com/project/docutils-ext","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/dotmpe.png","metadata":{"files":{"readme":"ReadMe.rst","changelog":"ChangeLog.rst","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-01-13T13:43:50.000Z","updated_at":"2018-06-17T17:28:25.000Z","dependencies_parsed_at":"2022-08-16T13:05:05.267Z","dependency_job_id":null,"html_url":"https://github.com/dotmpe/docutils-ext","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/dotmpe%2Fdocutils-ext","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotmpe%2Fdocutils-ext/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotmpe%2Fdocutils-ext/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotmpe%2Fdocutils-ext/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dotmpe","download_url":"https://codeload.github.com/dotmpe/docutils-ext/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240190927,"owners_count":19762593,"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-11T04:28:11.567Z","updated_at":"2026-06-06T23:30:15.710Z","avatar_url":"https://github.com/dotmpe.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Docutils extensions\n===================\n:Created: Aug. 2009\n:Updated: Dec. 2016\n:Version: 0.0.2-dev\n\n:Build status:\n  .. image:: https://secure.travis-ci.org/dotmpe/docutils-ext.png?branch=test\n    :target: https://travis-ci.org/dotmpe/docutils-ext/branches\n    :alt: Build\n\n:Package status:\n  .. image:: https://badge.fury.io/gh/dotmpe%2Fdocutils-ext.png\n    :target: http://badge.fury.io/gh/dotmpe%2Fdocutils-ext\n    :alt: GIT\n\n\n:rST writer:\n  .. image:: https://secure.travis-ci.org/dotmpe/docutils-ext.png?branch=test-rstwriter\n    :target: https://travis-ci.org/dotmpe/docutils-ext/branches\n    :alt: Build\n\n\nCollection of extensions on Python docutils.\nThis document attempts to present an overview of the project tree.\n\nA description is given of the command-line utilities in tools/,\nthen a list summary is given of the source code, whose main files will be\ndocumented themselves. Lastly a global log and list of further references\nfollows.\n\n.. contents::\n\n\nFeatures\n---------\nUtilities\n  - Command line user tools.\n\nrST Extensions\n  - Additional Du components.\n\nrST Writer\n  - Work in progress lossy rST writer for rst2rst publish.\n\n`rST Forms`_\n  A processor for Du documents to extract or insert (structured) user content,\n  with validation.\n\n`rST Outlines \u003cdoc/rst-outlines.rst\u003e`_\n  - Planning: Extract outlines from rST. See `Feature: Outlines`__\n  - `JSON outline \u003cfeatures/utilities-json-outline.feature\u003e`__\n    (`doc \u003cfeatures/utilities-json-outline.rst\u003e`__)\n\n.. __: features/outlines.feature\n\n\nDevelopment\n-----------\n\nCompleted\n'''''''''\n- Left- and right-margin decoration.\n- Various document transforms and additional document settings (with\n  command-line options). See `Transforms`_ (``dotmpe.du.ext.transform``).\n- These transforms are used by ``dotmpe.du.ext.reader.mpe.``\\ `Reader`.\n- Several Nabu `Extractor`, `Storage` pairs, see `Extractors`_ (``dotmpe.du.ext.extractor``) but nothing complex yet.\n- Monkey patched ``docutils.{readers,parser,writers}.get_*_class()`` to load\n  components from my lib. Enable 'extension' by importing ``dotmpe.du.ext``.\n\nIn progress\n'''''''''''\n- ``dotmpe.du.builder`` has some packages with specific Reader/Parser/Writer\n  component configurations, but frontend is undergoing work.\n- Front-end development in `Blue Lines`_. Simplified frontend for NodeJS.\n- rST rewriter.\n\nToDo\n''''\n-  Updated for Docutils 0.13\n-  re-evaluate include, literal and raw dereferencing.\n   want something like subdocs but low on the list of wannahaves.\n-  expose extractor and storage parameters on command line as other\n   components.\n-  create a storage context that can provide Nabu stores. see Extractors_\n-  ``--use-bibtex=USE_BIBTEX`` from latex2e may be nice practical example of\n   external resource framework/metadata integration.\n-  directive options are not all i18n'd\n- `Du/rST examples`_\n\n  -  example: form demonstration\n  -  example: example rSt on inline references and roles\n  -  example: breakcrumbs\n\n-  rST directives for breadcrumbs, testing etc? options?\n- `Issues`_\n\n\nDevel\n'''''\n-  Started docs per feature, to document specs, work to test scenarios.\n-  Fix accum. cruft in `Docs`_\n-  Validation. Relax-NG?\n-  I'd like an alternative (even less vertically hungry) markup for titles.\n   What about ``=== title`` or ``= title =`` block formats. Nice and short\n   where appropiate.\n-  Same point goes for tables (title would be header, left or right aligned etc.)\n   If rstwriter restructured is finished I might have stab at this.\n-  propose breadcrumb and other generate transforms on devel list,\n   Lea mentioned breadcrumbs (long ago..).\n-  Is the XML tree the complete representation whereof the rST is a variant,\n   a perhaps lossy representation? I think it loses some things, should keep\n   track during rstwriter devel.\n\n* `Branches \u003cBranchDocs.rst\u003e`__\n* `Journal \u003cDevLog.rst\u003e`__\n\n\nrST writer\n----------\nAlthough still heavily a work in progress, I think it may be almost ready for\nsimple rST-to-rST processes... should push through.\nTables may be low on the wishlist though, get everything else first.\nThen figure out nested parser for tables. Perhaps need to think about nested\nwriter for current literal blocks already?\n\nGetting Started\n---------------\n- May need latest docutils from SVN, sorry not sure about current version\n  but Du has not been in a lot of flux so..\n- For some automated tasks on this project package use ``make [help|..]``.\n- There is no setup script yet.\n- Skim the `docs`_.\n\nTesting\n-------\n::\n\n  make test\n\nruns some of the modules in ``test/``. See ``test/main.list`` for which.\n\nThe main development is at the rST writer. All test files are located in ``./var``,\nbasicly the bulk of the tests are based on comparison of output from the Du publisher.\n\nThis is the simplest way to test for absolute equivalent documents, ie.\n'lossless' publisher transormations. But that is quite a requirement, and probably\nonly applies to the ``rst2rst`` chain. I think fully lossless representation at this point should be considered more of a convenience than requirement\\ [*]_. The 'lossless' test approach is however suited to test the behaviour of chains of Parser, Reader, and Transform components when used with the ``pseudoxml`` writer.\n\nSo for testing of a document publisher, a check for all the content from the\nsource manuscript is the first device to have. What we really need is a Xanadu-esque\ndemuxer, to tell us which are the metacharacters, and what the corpus\\ [*]_.\nMaybe a writer that only picks out the character-data is something to be\nexplored for testing.\n\nUntil then, the main body of tests is run by the ``rstwriter`` module, running over all files from ``var/*.rst``. Test files are named and divided into seperate syntax topics.\n\nLossy tests are implemented by re-parsing the rST output, and doing (trying) a compare of the AST content and public attributes by generating and diff'ing the pseudoxml for both source and generated document. Iow. the test requires 3 publish actions, one of which the actually subject of test |---| that has the rST Writer component.\n\n\n.. [*] It will quite possibly require additional properties on the AST to support true lossless ``rst-to-rst``, since not all rST syntax choices are of consequences in other representations (ie. indentation depths). Rather, a rst2rst publisher may serve to normalize formatting, and also to run some transforms to reorder, renumber, rename, cross-reference, etc.\n\n.. [*] But we don't have one of those really. Until there is established and\n   accepted one, while virtually all modern virtual representation is an\n   inseperable mix of text and context.\n\n   The functionality of 'hyper'-text was defined long ago, as the relation of\n   arbitrary spans of text. Three sets of them: the subject, predicate and object.\n   This radically abstract method of hyperlinking is essentially what Xanadu '88 (now known as Green) was.\n\n   .. It is from such interoperable base, that an entirely new medium can arise of\n      not seen before level of expression. And it will be screaming for consencus,\n      for acception and rejection, sharing and keeping, generalizing or specifying.\n\n\nThe module is used as a crude test script during bugfixing::\n\n  python dotmpe/du/ext/writer/rst.py [\\*.rst]\n\nThis prints the documents in source and psuedoxml, conveniently side-by-side.\n\nCurrently only lossy rST writing is tested by 'make test' because\nthat generates enough work and bugreports for now.\n\nrST writer testcases are generated for all files matching ``var/test-*.rst``.\n\n\nDependencies\n''''''''''''\n::\n\n  pip install coverage\n\n\n- some symlinks in lib/\n- my mkdocs project to build from ``Rules.mk``\n- xmllint\n\n\n\n.. include:: .refs.rst\n.. .. include:: .refs.BranchDocs.rst\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotmpe%2Fdocutils-ext","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdotmpe%2Fdocutils-ext","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotmpe%2Fdocutils-ext/lists"}