WIP: python script for rst converstion

[Realtin]

Notes

How to convert to sphinx (old)

// add includes
xmllint --xinclude busctl.xml
// turn xml into rst
pandoc -t rst -f docbook -s busctl.xml -o busctl.rst
// turn rst into html
make html

Problem: Includes

All Includes: {'journal-iterate-unique.c', 'systemd.link.xml', 'version-info.xml', 'journal-iterate-foreach.c', 'sd_bus_error-example.c', 'user-system-options.xml', 'sd_bus_add_match.xml', 'print-unit-path-call-method.c', 'journal-iterate-poll.c', 'sd_bus_message_read_basic.xml', 'check-os-release-simple.py', 'event-quick-child.c', 'sd_journal_get_data.xml', 'id128-app-specific.c', 'ethtool-link-mode.xml', 'systemd.mount.xml', 'yubikey-crypttab.sh', 'common-variables.xml', 'standard-conf.xml', 'org.freedesktop.locale1.xml', 'send-unit-files-changed.c', 'systemd.netdev.xml', 'timedatectl.xml', 'journal-stream-fd.c', 'sd_bus_message_append_basic.xml', 'systemd.service.xml', 'system-or-user-ns.xml', 'journal-iterate-wait.c', 'print-unit-path.c', 'logcontrol-example.c', 'glib-event-glue.c', 'tc.xml', 'standard-specifiers.xml', 'fido2-crypttab.sh', 'journal-enumerate-fields.c', 'tpm2-crypttab.sh', 'cgroup-sandboxing.xml', 'vtable-example.c', 'threads-aware.xml', 'inotify-watch-tmp.c', 'systemctl.xml', 'supported-controllers.xml', 'hwdb-usb-device.c', 'notify-selfcontained-example.c', 'uki.conf.example', 'system-only.xml', 'sd-bus-container-read.c', 'sd_bus_service_reconnect.c', 'check-os-release.sh', 'notify-selfcontained-example.py', 'path-documents.c', 'sd-bus-container-append.c', 'vtable-example.xml', 'check-os-release.py', 'vpick.xml', 'importctl.xml', 'standard-options.xml', 'libsystemd-pkgconfig.xml'}

Code Includes: {'journal-iterate-unique.c', 'journal-iterate-foreach.c', 'sd_bus_error-example.c', 'print-unit-path-call-method.c', 'journal-iterate-poll.c', 'check-os-release-simple.py', 'event-quick-child.c', 'id128-app-specific.c', 'yubikey-crypttab.sh', 'send-unit-files-changed.c', 'journal-stream-fd.c', 'journal-iterate-wait.c', 'print-unit-path.c', 'logcontrol-example.c', 'glib-event-glue.c', 'fido2-crypttab.sh', 'journal-enumerate-fields.c', 'tpm2-crypttab.sh', 'vtable-example.c', 'inotify-watch-tmp.c', 'hwdb-usb-device.c', 'notify-selfcontained-example.c', 'uki.conf.example', 'sd-bus-container-read.c', 'sd_bus_service_reconnect.c', 'check-os-release.sh', 'notify-selfcontained-example.py', 'path-documents.c', 'sd-bus-container-append.c', 'vtable-example.xml', 'check-os-release.py'}

Solution in Sphinx

Includes in sphinx: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude
.. literalinclude:: example.py

Solution in Pandoc

• https://github.com/pandoc/lua-filters/tree/master/include-files
  ```{.include}
  chapters/introduction.md
  chapters/methods.md
  chapters/results.md
  chapters/discussion.md
  ```

Problem: "Entity References"

lots of files use "Entity References" in xml and pandoc can't handle it

Solution in Sphinx

https://documatt.gitlab.io/sphinxcontrib-constdata/
sphinxcontrib-constdata is the extension for Sphinx documentation projects that allows showing values, listing tables, and generating links from CSV, JSON and YAML files.

Solution in Pandoc

• https://pandoc.org/lua-filters.html#replacing-placeholders-with-their-metadata-value

Problem: Code Includes

Solution in Pandoc

https://github.com/pandoc/lua-filters/tree/master/include-code-files

```{include="hello.c"}
```

Problem

/tools/xml_helper.py

Problem: Tables !!!

see: standard-specifiers.xml, vtable-example (should this be turned into rst?)

Problem: Includes are more difficult?

<para id="plural"> seems to identify specific paragraph of an include (is removed in the rst translation)

<xi:include href="threads-aware.xml" xpointer="getenv"/> still ignored

TODOs:

• <xi:include href="version-info.xml" xpointer="v198"/> --> %v198% (convert to placeholder)

• convert version-info.xml for palceholder use

• Handle Entity References as placeholders (by hand)

• convert custom-entities.ent.in for placeholder use

• code includes? <programlisting> (but needs manual adjustments)

• convert included section files to rst (currently listed in ignored files)

• put all rst in a folder ?

• manual adjustment of:

  • Includes (search for {.include})
  • Code Includes (search for {include=)

• run pandoc to resolve includes & run sphynx

• document rst and sphinx command

• custom-entities.md needs to be filled?

• ethtool-link-mode.xml is used as an include but is in a different folder!!

• <citerefentry><refentrytitle> ? don't get a special formatting is that needed?