[TIMOB-27790] Docs as Code
GitHub Issue | n/a |
---|---|
Type | Epic |
Priority | None |
Status | Open |
Resolution | Unresolved |
Affected Version/s | n/a |
Fix Version/s | n/a |
Components | n/a |
Labels | n/a |
Reporter | Christopher Williams |
Assignee | Christopher Williams |
Created | 2020-03-05T18:44:00.000+0000 |
Updated | 2020-03-23T13:47:28.000+0000 |
Description
We've automated our "legacy" process for publishing docs, which consist of two major doc types:
- API Docs
- Guides
Guides currently come from our Wiki and are published to docs.appcelerator.com (after being exported as HTML and massaged), and we also trigger a wiki crawl from Zoomin to publish the contents to Zoomin/docs.axway.com
APIDocs live as xml files in our titanium_mobile repo, and we use custom node scripts to generate jsduck JS files, then run that through a fork of jsduck to generate the docs.appcelerator.com website.
Moving forward we'd like to move away from the wiki as source of our Guides content towards markdown files living in a Github repo (probably directly in titanium_mobile?). How can we extract the current wiki contents into markdown? Clean it up? Remove outdated docs? And then how does that get published out to Zoomin?
We'd also like to take our API docs and combine efforts with the Dublin team that already published their API docs out. We need to find a way to incorporate multiple products in the same doc website, while hopefully leveraging [~jvennemann]'s work on his prototype: https://appcelerator.github.io/titanium-docs/api/
Some follow-up: * The Dublin teams' [docs-as-code site](https://axway-open-docs.netlify.com) *does not* appear to be API docs, but instead equivalent to "Guides", and an email thread more or less states it's equivalent to "staging" and needs to be pushed/synced up to Zoomin/docs.axway.com ** As to how we'd merge in our guides, the [current process](https://axway-open-docs.netlify.com/docs/contribution_guidelines/) means we'd need to host our markdown files in their repo: https://github.com/Axway/axway-open-docs/tree/master/content/en/docs ** This feels a little odd to me that *every* product would have their guides/docs live in this repo, rather than in their own product's repo - but then there's an issue of right to edit the docs versus the src of the product and whether repos are public/private, etc. Maybe it'd make sense for some products like ours to use submodules or push/sync docs between repos? Or maybe we just stick a pointer in our repo to the open-docs repo location where they live? * Most of the actual API docs I can find seem to live under https://docs.axway.com/category/api and are all server-side APIs. ** Most of them use a Swagger UI to show the APIs (see http://apidocs.axway.com/swagger-ui/index.html?productname=transfercft&productversion=3.5&filename=transfercft-swagger-api.json#/) which is obviously geared towards REST server APIs ** AMPLIFY Central DevOps API apparently uses [Stoplight](https://stoplight.io/documentation)
Potential ways forward: * Do a one-time conversion of our wiki content to markdown files and push to open docs repo ** Confer with their team in advance, ensure that it gets pushed to docs.axway.com/Zoomin ** Modify our doc publishing to use the markdown files as input for guides? (until we can decommission docs.appcelerator.com) ** Take down the wiki * Work out where API docs should live (especially non-server ones like ours!) ** Add to header of Open Docs site?
https://github.com/Axway/axway-open-docs/pull/472
https://github.com/Axway/axway-open-docs/pull/489