e4s-project/e4s-documenter

A tool to generate documentation for a project based on project metadata (README, Changelog, License, etc.) stored in a yaml file.

e4s-documenter's Issues

E4S Documenter Design Requirements

At this early stage of development the E4S Documentation Aggregator remains quite flexible in its design. We would like feedback on features, data formatting, use cases, future-proofing and anything else that should inform the development of this project to make it as useful and straightforward to work with as possible.

Current design considerations and summaries of the the prototype's functionality are available in this document: https://docs.google.com/document/d/1FKARSiTC53Twdfl823AYJl1CeACQDAH06Q6hrPuCauM/edit?usp=sharing

E4S-Documenter no longer correctly detects Accelerator Variants with new Spack

Summary

As of Dec 4 2023, the E4S-Documenter no longer correctly detects Accelerator Variants from the output of spack info, resulting in garbled/incorrect output on https://e4s-project.github.io/DocPortal.html

Example package, before Dec 4 2023:

Same package, after Dec 4 2023:

Observations

Note the Accelerator Variants field no longer correctly lists the supported variants, despite the fact the spack variants for this package have not changed. Further, this defect is not specific to one package - I believe all packages with previously non-empty Accelerator Variants have been subjected to similar corruption.

Analysis

I believe the root cause of the problem is the variant output of spack info recently underwent major reformatting changes, see Spack PR 40998. E4S-Documenter parses this output to detect Accelerator Variants, and as a result of the formatting changes the parsing logic is no longer correct.

Specifically, this line in the parsing logic assumes there is a blank line in the spack info output between the text Variants: and the start of the variant list. However, that blank line has been removed (see images in Spack PR 40998). As a result, the parsing logic now entirely skips the block of text containing the spack variants and instead searches the next section of the spack info output, which varies by package. In the package shown above that section happens to be the info regarding a when +cuda conditional variant, which is why the string "cuda" was still found (by chance) and Accelerator Variants: CUDA was printed. In other packages that next info section can be something completely different that doesn't happen to contain any textual references to accelerators, resulting in blank output for Accelerator Variants.

Explore automated detection of which metadata files are present in a product repo

The e4s_product.yaml file presently lists which files are present in each product repo. I think it would be better to discover which files were present by looking for them as part of the raking process. This way, product teams could add a new file and it would be discovered automatically.

In general, I think it would be better to have no information other than the base URL in the e4s_product.yaml file.

Perhaps you are already moving in this direction, but want to make sure.