Skip to content
New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Add internal links to XenAPI reference #6315

Merged

Conversation

contificate
Copy link
Contributor

Adds a simple parser for Xapi type expressions that is used to rewrite the types shown in the XenAPI class reference to include links to relevant documentation.


image


The parser is structured in the form of a Pratt parser. This may seem like overkill, but it keeps the door open to extension. Also, the parser must work with limited information (it has no knowledge of XenAPI object names). It works by noting that object types are always (?) suffixed by a type constructor, e.g. VM ref - therefore, it assumes any prefix form must be a valid class name, then subsequent left denotations take the left as a type parameter (for which all are unary, except map which has an alternative syntax that is special cased).

Currently, the only interesting parts of the "rendered" type are:

  • Enum names become links that should scroll and temporarily highlight (flash) the relevant details.
  • Object names become links to their relevant page in the documentation.

However, other structure is retained, such as where builtin (primitive) types are (e.g. int, bool, string, etc.), constructors names (ref, set, option, etc.). In future, these could link to relevant portions of a new article that explains all the types (for example, the format of datetime is perhaps non-obvious to someone reading the XenAPI reference pages).

Adds a simple parser for Xapi type expressions that is used to rewrite
the types shown in the XenAPI class reference to include links to
relevant documentation.

Signed-off-by: Colin James <colin.barr@cloud.com>
@contificate
Copy link
Contributor Author

This is done at page load time so that it's more easily removed if the old functionality is retained. You need only remove the 2 lines at the end that rewrite all .inline-type elements.

@contificate contificate added this pull request to the merge queue Feb 21, 2025
Merged via the queue into xapi-project:master with commit df42cde Feb 21, 2025
15 checks passed
# for free to join this conversation on GitHub. Already have an account? # to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants