[TIMOB-27814] Create scripts to convert YML APIdocs to docsy-compatible markdown
| GitHub Issue | n/a |
|---|---|
| Type | Story |
| 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 | Unknown |
| Created | 2020-03-23T13:38:46.000+0000 |
| Updated | 2020-03-23T14:11:34.000+0000 |
Description
[~jvennemann] has already created tooling to do this for his prototype Vue-based doc site (https://appcelerator.github.io/titanium-docs/api/)
We'll need an automated way to consume our existing apiece YML format and output set of docsy-compatible markdown files that could be pushed to Open Docs.
The goal is to eventually publish the APIDocs as part of the open docs website.
The open issues/questions here are whether that is the right place for publishing API docs/references since they don't currently have any there. docs.axway.com has some auto-generated swagger UI API references for server products: https://docs.axway.com/category/api
I think it is very important to have Guides/API docs on one page. I don't want to navigate to a different page just to lookup API docs. Another question would be how do we properly integrate Titanium related content into the current Open Docs site structure. I mean we have a ton of content when we export all our guides and include API docs. As far as i can see it just has one navigation bar to the left where all the guides are listed. I don't think it's a good idea to just dump our Titanium related stuff there as well. This would create a massive navigation bar that is hard to navigate. We have the exact same issue in our existing docs now, where it is almost impossible to find anything in the left navigation bar because it has tons of links. In regards to the existing tooling: I created a raw JSON output [generator](https://github.com/appcelerator/docs-devkit/blob/develop/packages/titanium-docgen/generators/json-raw_generator.js) of our parsed YAML files that might be useful for this. It leaves all fields that contain inlined markdown (like description and examples) as is for further processing. In the VuePress prototype I use the JSON data to dynamically render the API docs in Vue. It shouldn't be too hard to to write a docsy compatible renderer around the exported JSON data that generates a Markdown file for each type. Another question is if we can properly render API docs in pure markdown. I explicitly made this part in the VuePress prototype dynamically rendered by Vue since i felt that pure Markdown wasn't able to display all the available info in an appealing and well structured manner. So we might need a mix of Markdown / HTML, but i guess Hugo should support that as well.