Open simenandre opened 4 years ago
This is a great idea and something we actually have on our Jira backlog. 😃 Thanks for describing a possible solution – it sounds indeed like something that could work for us.
👋
During the summer, I implemented a version of this flow on tabetalt/docs. The design consists of a plugin, namely docusaurus-multiple-docs
, I had to build this library.
A few thoughts after having used this setup a while:
You'll get locked into docusaurus
with it, which could be fine, but I like the least amount of specialized files in each of the repositories. We had to make some extra functionality to retrieve CHANGELOG
(which is something we need at Tabetalt).
If I was going to do it all over again.
# sdk.yaml
name: Typescript
version: 1.3.4
repository: https://github.com/.../...
links:
- name: Getting started
file: getting-started.md
- name: Changelog
file: CHANGELOG.md
...
It would probably be less work than I spent on Tabetalt's setup and it could be used in a template as well. Furthermore, if you ever decided to go this route, I'd be interested in building it again and subsequently update Tabetalt's setup.
Hello! 👋
In most cases, developers are looking to use one of the SDKs. Many of the other API businesses out there expose their SDK documentation along with quick start guides and examples. And I think from a developer point of view, it would be nice to add that to this repository too.
I really like Pulumi's setup. They utilize a build script that collects API documentation from each of the repositories and adds those Markdown-files to their website. Maybe something like that would work here as well?
I wouldn't do exactly like Pulumi since they convert comments from source code to Markdown in the same sequence as they are pulling them. In Swedbank Pay's case, I would suggest that every official SDK have a standardized
docs/
folder. This would serve as documentation for the developers that find it directly on Github, but also could be rendered in HTML under developer.swedbankpay.com. I would haveREADME.md
that would be the introduction to the SDK (also for the HTML counterpart) and typical quickstart files and examples altogether.I'd say something like this could work:
From this, a simple script could populate SDK documentation. Pulling down all
docs/
folders periodically (or with every SDK release). Alternatively, one could deploy SDK documentation from every SDK. However, this would probably cause more headache.What do you think of the idea?