aclist
chore: add sphinx documentation
This PR overhauls the documentation as discussed in https://github.com/aclist/kbin-kes/issues/454 and https://github.com/aclist/kbin-kes/discussions/362#discussioncomment-12397117
A README.md, Makefile, and other build scripts are provided.
Migration to Sphinx
Documentation was ported from Asciidoctor to Sphinx, although this was ultimately a near total-rewrite. There were many vague, missing or out of date sections in the old documentation, and the API reference was incomplete at best.
Rather than recycle assumptions from the old documentation, the new documentation has overall been written from the standpoint of the 5.0.0 release and forward-looking changes. Not all of those changes are in yet, so the documentation represents where MES is going, rather than where it is. As such, all outstanding framework changes must be merged before this documentation, including, for example, https://github.com/aclist/kbin-kes/pull/490.
Document new enums
- Resolves https://github.com/aclist/kbin-kes/issues/406
- Resolves #455
- Additionally, documents new
Triggersenums introduced in https://github.com/aclist/kbin-kes/pull/497 - Also documents new
Themeenums introduced in https://github.com/aclist/kbin-kes/pull/485/commits/3b2c37fbae3925efec1ba232d9922add3369b4d4 (pending merge) - Also resolves https://github.com/aclist/kbin-kes/issues/317
Utility function reference
Functions are more richly documented now, with all params, return types, and examples listed. Cross-references (xrefs) are provided to jump to related function definitions or enumerations. A custom style has been applied to make function and method xrefs more clearly distinguishable from builtins (which are not links) on hover.
safeGM
safeGM has been given its own section in the documentation, rewritten from the vantage point that it is going to be refactored to support methods, as described in https://github.com/aclist/kbin-kes/issues/502.
Enums
Similarly to the above, the enums have been written from the vantage point that the uppercase notation from #502 is going to be used.
MES enums are not class-based. They are naive frozen objects with constant integer values. This datatype was not clearly supported in Sphinx out of the box, so I faced the choice to either extend it by writing a custom directive for the JS domain, or using the .. js:attr:: directive to list the members as a series of attributes. Sphinx does support creating a global module under which attributes are namespaced, but this causes the attributes to not look and feel like traditional enum documentation (PyGtk enums for reference).
To emulate this style, I opted for the workaround of appending a custom class to the enum namespace and members, respectively. CSS is then applied to give the members a discrete appearance and show the integer enumeration. Albeit a kludge, this is reasonably simple for our purposes and achieves the intended effect without additional work.
JSON schemas
JSON schemas have been introduced for the main manifest and for all subschemas describing settings menu types like radio, select, color, etc. Required and optional properties are explicitly listed now, and the datatype of each property is listed, as well as enumerations of which (and how many) values are permissible. This section also resolves https://github.com/aclist/kbin-kes/issues/317, stating upfront that the state key is reserved.
Rather than a loosely defined example JSON blurb, the schemas should make it absolutely clear how the JSON is to be formatted for every requested setting type, and links to the raw schema JSON are provided for reference.
Known issues
As a side effect of not namespacing the enums under module names (e.g., under default Sphinx behavior, the member LOG = 1 would instead be listed as Log.LOG = 1, with the enumeration including the namespace), there is the possibility of collisions between :js:attr xrefs, since they share the same domain. For example, Mbin.Thread.COMMENTS might be seen as the same as Mbin.Domain.COMMENTS, depending on how the document is traversed during compilation. For the most part, Sphinx traverses auto xrefs correctly, but there was one xref that was getting resolved to the wrong internal anchor.
For now, I've added a monkey patch (patch-1.sh) in the directory root that simply seds the offending anchor and updates it to the correct ID to deduplicate it. There was only one xref collision.
The fa-clipboard icon shown on the main menu legend page does not match 1:1 with the clipboard icon in MES, I think because Mbin is using a different fontawesome version from the one being sourced in Sphinx. I'll try to see if this can be overridden, but it's a minor thing.
TODO
- [x] The majority of utility functions from
helpers/safeGM.jswere documented, but still to be added are the functions and methods aroundloadMags()from https://github.com/aclist/kbin-kes/pull/335 - [x] The page enums from #456 haven't been added yet.
- [x] There is ample documentation around the
Triggerenums, but would like to add a tangible example of how this functionality works with an example code block - [x] Add mention of the developer mode requirement from https://github.com/aclist/kbin-kes/issues/348
@Pamasich to review this, I would recommend building the HTML files directly and inspecting the rendered page, as there are a lot of miscellaneous build artifacts and small files that won't provide much information on their own. If building locally proves to be an issue, I can host the docs on a subdirectory of GitHub pages somewhere.
I added a couple of TODOs to this, so going to convert it back to a draft. If you want to pre-review it, I can incorporate any feedback on a rolling basis.
The fa-clipboard icon shown on the main menu legend page does not match 1:1 with the clipboard icon in MES, I think because Mbin is using a different fontawesome version from the one being sourced in Sphinx. I'll try to see if this can be overridden, but it's a minor thing.
The library https://github.com/sphinx-contrib/icon uses more modern (fa5 vs fa4) icons, but has an outstanding bug that prevents the compiled HTML from using relative paths.
This is complete on testing, with the proviso that the public HTML must be compiled and uploaded to GitHub pages once ready.