[OIL] Split the API reference markdown into smaller files and use templates to generate it. #5338
Conversation
| @@ -1,3 +1,7 @@ | |||
| --- | |||
There was a problem hiding this comment.
These headers are a particularity of XS docs. If there is an issue with having them here, I can remove them and have the pipeline insert them later (since it will have to replace the @root@ placeholders in some files anyway).
|
|
||
| # API Reference | ||
|
|
||
| Version **@xapi-version@** |
There was a problem hiding this comment.
Is there an easy way to have this replaced during build time? If not, I can have the pipeline replace it later).
There was a problem hiding this comment.
Currently, the version is embedded into binaries using the Xapi_version module and using the dune-build-info library. One way to do it would be to it would be to create an ocaml binary that processes this file.
One way you can try is to use dune subst, and use %%VERSION%%. I believe it's intended to be used project-wide, but you're welcome to try
There was a problem hiding this comment.
Thanks for the tip; I won't consider this as a blocker for this PR though (it's probably not a big change, but I only have time to work on this on and off, so I'd rather get the PR in the soonest possible and improve the versioning later).
There was a problem hiding this comment.
Had a look, and the binary that generates the files already has access to this library, So it can already use mustache templates to generate it.
The only complication is that the binary needs to be "installed" before it generated the files so it can pick up the version, because of how dune injects the version, I've done this in psafont@13da274
But it needs testing to ensure that the version injected in the CI is simply the tag, and not either of these types:
# API Reference
Version 23.32.0-52-g13da274
# API Reference
Version 24.999.999-dirty
(this happens when the commit is untagged, and when make is run before make doc, respectively)
There was a problem hiding this comment.
As discussed, building in the CI yields 0.0.dev. In the interest of avoiding taking up too much of people's time, I can always leave it as is and replace it later in the pipeline alongside @root@.
kc284
force-pushed
the
api-ref
branch
2 times, most recently
from
d107868 to
8db76b3
Compare
|
Note that this PR does not necessarily need Interfaces reviewers. |
| @@ -0,0 +1,6 @@ | |||
| (alias | |||
There was a problem hiding this comment.
this is an alias with a name and dependency, but where is the action?
There was a problem hiding this comment.
No action, just using source_tree to include all the files that will be generated in here. We have a few more dune files with rules like this.
| dune exec --profile=$(PROFILE) -- ocaml/idl/datamodel_main.exe -closed -markdown $(XAPIDOC)/markdown | ||
| cp ocaml/doc/*.dot ocaml/doc/doc-convert.sh $(XAPIDOC) | ||
| #markdown | ||
| dune build --profile=$(PROFILE) -f @ocaml/idl/markdowngen |
There was a problem hiding this comment.
we could define some install sections in dune and let dune install things into the right places. The method of installing files in the Makefile was from the time when we didn't have dune.
Then also the version substitutions inside the markdown files might work
There was a problem hiding this comment.
There was a problem hiding this comment.
Unless I'm missing something, it doesn't seem to me that I can do this efficiently with the version of dune we're currently using. All the useful stanzas (source_trees, glob_files, include) have been added in various 3.x versions.The install sections I see in other dune files in the repo handle single files, but here there is a good number of autogenerated files that have to be installed.
|
Is there a way to check the output of this PR? For now I can see that classes.png is not being generated from classes.dot (this is generated by running doc-convert.sh) |
|
How nice, that hasn't happened since before the introduction of GPU datatypes :( |
kc284
force-pushed
the
api-ref
branch
2 times, most recently
from
36219ef to
14999d9
Compare
There was a problem hiding this comment.
One last comment. This may need input from other xapi devs:
Certificate's description is just the word "Description" and Bond doesn't even have one.
We could add them in this PR, maybe?
I was thinking @psafont or @edwintorok could weigh in on a proper description
| diagramatically, using crow's foot notation to specify one-to-one, | ||
| one-to-many, or many-to-many relationships: | ||
|
|
||
|  |
There was a problem hiding this comment.
I'm a bit confused, where is this image in the source? I can see it on https://xapi-project.github.io/xen-api/ but not here. :/
There was a problem hiding this comment.
It's autogenerated from the .dot file. The internal pipeline does it, I haven't looked into github actions because that was done a long time ago (and I'll consider it out of scope for this PR).
For Certificate, the description can be "An X509 certificate used for TLS connections". For Bond, maybe "A Network bond that combines physical network interfaces, also known as link aggregation"? |
|
Thanks @psafont, I'll add these. Note that there are several more missing or suboptimal descirptions in xapi (secret is a notorious one), I think we need a separate PR to fix all those. |
… to generate it. Signed-off-by: Konstantina Chremmou <[email protected]>
Signed-off-by: Konstantina Chremmou <[email protected]>
|
I also rebased on master. The changes requested are in a separate commit, see here 37821d8 |
The API reference file has become too big (~1.5MB) and keeps increasing. The result is that the corresponding webpage takes several seconds to download, so we decided to split it to smaller bits and have a file per class.