Auto-generating a documentation site from the FoI extensions github

rileypb · March 18, 2023, 5:05pm

I’m interested in (as the title says) generating a publicly-accessible documentation site for the extensions in the Friends of Inform extensions github. I just need to figure out what tool generates extension HTML. I’m currently exploring the Inweb github but it’s a real maze. Anyone have any insight here?

CrocMiam · March 18, 2023, 9:02pm

Searching “census” might help.
It’s a flag to tell inform to scan the extensions & generate the docs.

github.com

ganelson/inform/blob/fae7ecc9d673e218ac8c04bd2f664df58c8d4b02/inform7/Manual/Interacting with the GUI.w#L65


      
          However, note that it is not an error to install an extension with
          the same name and author as one in the built-in extensions folder. This
          does not result in overwriting, since the newly installed version will live
          in the external area, not the built-in area.
          
          
An extension may be uninstalled simply by deleting the file: but the
          application must not allow the user to uninstall any extension from
          the built-in area. We must assume that the latter could be on a read-only
          disc, or could be part of a cryptographically signed application bundle.
          
          
@h The extension census.
          The Inform application should run Inform in "census mode" in order to
          keep extension documentation up to date. Inform should be run in census mode
          on three occasions:
          
          
(a) when the Inform application starts up;
          (b) when the Inform application installs a new extension;
          (c) when the Inform application uninstalls an extension.
          
          
When |inform7| is run in "census mode", it should be run with the command |-census|.
          All output from Inform should be ignored, including its return code: ideally,

Zed · March 18, 2023, 9:35pm

inweb is the thing that takes literate source and makes two kinds of things with it: Woven web pages (like Inweb web page) and the Tangled executable.

The extension web page generation code isn’t standalone. Documentation renderer. But as @CrocMiam indicates, inform7 will generate it for you.

$ mkdir external
$ cd external
$ git clone https://github.com/i7/extensions
$ ln -s extensions Extensions
$ inform7 --external . --census
$ cd Documentation
$ ln -s /path/to/inform/resources/Imagery/doc_images .
$ perl -pi.bkp -e 's{inform:/doc_images}{./doc_images}g; s{inform://Extensions/Extensions}{./Extensions}g' *.html

The results of this are intended for the consumption of the IDEs, and they contain bogus inform:// URI’s. So if you open what you end up with in external/Documentation/Extensions.html in a browser, the results will be a mess. The link to doc_images above and the perl one-liner will make the links and images in Documentation/Extensions.html work ok; some more complicated transformation would be needed to make the individual extensions look ok.

I hesitate to mention it, since it’s not published or in any condition to be useful to anyone else and I’m not sure when I’ll get back to it, but I already have code that does a fairly credible job of creating web pages like this. Link completely not guaranteed to stand the test of time: v10.1 extensions as of one particular version prior to release. This isn’t a transformation of the compiler’s output; it does its own lexing and syntax-highlighting. The results are messy for some tables, and the chapter/section headers aren’t highlighted right for the docs and there are doubtless other things wrong.

rileypb · March 19, 2023, 12:48am

Well I managed to do it, but it’s not fully automated yet. My lousy hosting service doesn’t seem to support using ssh keys for sftp, which is a problem. Anyway, my cert is broken or I’d point you at the site.

rileypb · March 19, 2023, 1:23am

Okay, this is better: Extensions

Edit: Needs a return to index icon on each page, but other than that it seems okay.