Allow self-hosting of custom site-specific user and operator documentation #200
Conversation
| - name: https://github.com/azimuth-cloud/ansible-collection-azimuth-ops.git | ||
| type: git | ||
| version: 0.13.2 | ||
| version: feat/mkdocs # 0.13.2 |
There was a problem hiding this comment.
TODO: Revert this before merging.
| As part of the standard Azimuth deployment procedure, a copy of the generic user and operator | ||
| documentation sites are published on separate subdomains of the Azimuth ingress URL. For an Azimuth | ||
| instance hosted at `portal.azimuth.example.com`, the documentation can be accessed at | ||
| `user.docs.azimuth.example.com` and `admin.docs.azimuth.example.com` respectively. The operator |
There was a problem hiding this comment.
Would it make sense to use operator.docs.azimuth.example.com instead of admin.docs.azimuth.example.com? Would match how it's being referred to in this section.
There was a problem hiding this comment.
Yeah probably, I flip-flopped between admin and operator a few times while putting this together. I guess we should settle on one or the other for consistency before finalising the changes.
There was a problem hiding this comment.
I fact, that's a mistake in the docs because I also changed my mind and went for user-guide and admin-guide as the subdomains after writing those docs 🤦
There was a problem hiding this comment.
I do like "Azimuth operator" but consistency across the docs is best, whatever we choose.
| service="zenith-server-registrar" | ||
| remote_port="80" | ||
| ;; | ||
| azimuth-api) |
There was a problem hiding this comment.
Why do we need this, isn't it available by ingress anyway?
There was a problem hiding this comment.
It's useful for doing development work on the Azimuth UI because you can just run a port-forward to the API and then start the UI on localhost with npm run dev rather than having to do the full tilt-based development setup. Not really part of this PR but just a local change I had lying around that I accidentally included here. I can move it to a separate PR instead.
|
@sd109 I was gonna put this in the user-docs repo, but since you're refactoring and moving it out it may as well be here At STFC we've had to do a lot of user docs updates to bring them up to date, i.e. with the switch away from Kubeapps. A lot of our changes are service specific (we've made changes to apps; and currently have CaaS disabled), but you're still more than welcome to take anything that's useful to you from our fork, to reduce the amount of doc-writing. |
|
Thanks very much @AlexCK-STFC - I did stumble across that STFC repo the other day and was ashamed that we'd taken so long to update our docs that you'd started writing your own... This self-hosted docs PR has also unfortunately taken a back seat due to other priorities recently but I am still hoping to get back to it eventually. If there are any parts of your docs which are more widely applicable rather than STFC-specific then we'd be delighted to see them as one or more PRs on our azimuth-user-docs repo. |
This PR adds the ability to build and publish the Azimuth user documentation on a subdomain of the main Azimuth URL.
It depends on azimuth-cloud/ansible-collection-azimuth-ops#732 which in turn makes use of https://github.com/azimuth-cloud/mkdocs-helm to build and publish the documentation sites.