Generate API docs from NUnit source code #843
Conversation
Since we're generating it by build
Since that's where the release will be added
|
CC @OsirisTerje -- FYI, I'm getting started on this. :) |
|
OK, at this point I can get it building locally and via GitHub actions with the v4.0.0 release. 🎉 Next up: Make it look nice and incorporate it as I've seen other sites do. Going to take a look around and come back to this. |
|
I'm going to sleep on this and return to it. Some issue with not being able to find the index.md file that seems to be right there when I look at it. Also, might need to check out some of the exclusion rules to ensure that file isn't being overwritten because of the metadata generation. |
This comment was marked as outdated.
This comment was marked as outdated.
only available when actually building
.url is for prod
LOL !!! My eyes was hiding that! Never looked up there. See that the menu also is there in the current docs page, but I have never noticed it ! Perhaps we can do more out of that one ? Ref #848 |
|
Thanks for putting this together @SeanKilleen I haven't time to review it comprehensively unfortunately, but I like what I've seen so far. The "View Source" link is particularly handy. A workflow question: I understand the markdown docs are published as PRs are merged into this repo. Would framework-derived info like this be regenerating them as part of each release? How would versioning work over time as the API evolves across releases? |
Great question! As of now, the way it works is the docs build points to a hard-coded release number of NUnit that I'd need to update each time. Our CI process pulls the asset from the release , unzips it, and moves it to a place where docfx knows to look for it. Before this PR is merged I'll try to add a one-liner command in the dev container so people working with it there can easily pull in this part transparently. Shortly after this is merged, I intend to follow up on it and set it to always pull the latest package from a semver perspective, which will keep it all up to date going forward. |
|
Alright, since the consensus is that people don't hate it, my next steps are:
|
|
|
@nunit/core-team in the interest of moving forward, I'm going to merge this. For next steps:
|
SeanKilleen
changed the title
* Ignore the API directory Since we're generating it by build * Add docfx generation commands * Ignore code-output folder Since that's where the release will be added * Readme instructions for local use * wrap * Action to get NUnit asset * unzip and copy * verbose unzip * unzip into subdir * adjust syntax * adjust syntax * adjust syntax * more * more * I must be a little sleepy. * only ignore YML and manifest files * Add API index * Add API reference to docs index * Adjust TOC file * Remove index (not needed) * Let's try out previews of the docs, because why not * limit step to PR only * remove context flag only available when actually building * Only clean up on PRs * Update to use deploy_url .url is for prod * Attempt to add a preview link comment * quick test of devcontainer script * Let's see. * Install unzip * remove the zip file * fix directory * move instead of copy * Set flag to overwrite * back to copy * more * There we go. * aliaa * comments * alias * Contributing updates on one-liner commands 7d74c0a
NUnit 4.0 has me feeling bold. :) Figured I'd take a first shot at pulling in API docs from NUnit's xmldoc comments, as docfx can do.
The docs, as we know, are not in the same repo as the code, so our build process and any manual experimentation will have to copy some files into a folder in the docs project.
Work
Link to some kind of API landing page (reference some other repos that use docfx to see how they do it)Have it always pull from the latest NUnit release, semver-wise.Filter out the internal namespaces (get input from Core team)