Polyglot docs #104
Comments
|
@jroper Antora how one of the variants. I seeing that Tim worked on migrate Lightbend Tech Hub to Antora. 😄 |
|
@jroper Would that apply to shared protobuf files for the CloudState protocol too? Together with the documentation they are shared with the main CloudState repository. If a support library builds in its repository by itself, it would have to download/copy over from somewhere. Would that be a similar shared artefact? |
|
I've created a shared paradox theme and plugin at https://github.com/cloudstateio/cloudstate-paradox. Updated the main documentation to use this in #339. For publishing the separate docs for language support modules: since we're using github pages, a simple approach would be publishing docs to the We could update the structure of the docs and publish everything under the one https://github.com/cloudstateio/docs repo. So we could change to having something like: If we're changing structure, we may want to introduce the possibility for doc versioning as well. So we could have Note that with this simple approach to separate docs, there won't be shared navigation. It will be like the separate module docs for https://akka.io/docs/ |
|
Docs from master now publish to https://cloudstate.io/docs/core/snapshot/ Have manually published current docs for previous tag: https://cloudstate.io/docs/core/current/ The old docs are still there under https://cloudstate.io/docs/ And I'll start breaking out the language support docs. |
|
I've removed the old docs now, updated links for Lightbend Cloudstate docs, and created a simple new docs index at https://cloudstate.io/docs/ using the cloudstate.io site styling. |
|
Separate docs for language support modules:
|
|
If the separate repos for all languages exist now, this is easy enough to do. Antora can publish from multiple repos and make it look as if it is all one doc set. Or, if the docs for each language get large and complex enough, they can be published as separate "components" meaning the reader would have to select the component from a separate menu. I prefer the former because I think it is simpler for the reader. @pvlugter, I see you checked off Go and Python, does this mean you have already separated these docs? If so, could you point me to the repos? Thanks! |
|
The Cloudstate Go docs are here, in the Go support repo: https://github.com/cloudstateio/go-support/tree/master/docs The current version is published to https://cloudstate.io/docs/go/current/ which is an alias for https://cloudstate.io/docs/go/0.1.1/. Snapshot version of docs from master published to https://cloudstate.io/docs/go/snapshot/. Similarly for Cloudstate Python (just the shell of docs currently): https://github.com/cloudstateio/python-support/tree/master/docs And the Cloudstate Spring Boot docs are being added here: https://github.com/cloudstateio/springboot-support/tree/master/docs The core docs are under the main https://github.com/cloudstateio/cloudstate repo, and published under similar versioning with current here: https://cloudstate.io/docs/core/current/ (which is currently version 0.5.1). These all use the theme and sbt plugin from https://github.com/cloudstateio/cloudstate-paradox Sounds good if Antora already has support for multiple repos. Note that each module has its own versioning and release cycles. For example, Cloudstate core is currently 0.5.1 and Cloudstate Go is 0.1.1 and so on, and these are released separately. If these are being converted to Antora now, then I'll pause the work here. |
|
@pvlugter, I'm converting the docs in the cloudstateio/cloudstate repo now. Per your checklist above, I'll only convert the Javascript and JS language docs as part of this effort. So, you can continue splitting off the others into their respective repos if you like. I will tackle conversion later, but for now I'll link from the cloudstateio doc to the snapshot you are publishing for Go and python. Once they are converted, I can include them instead of linking to them. The Cloudflow team has described how they use Antora versioning here: https://github.com/lightbend/cloudflow-enterprise-docs#updating-a-current-version-of-the-documentation. However, I have to think through how this will work with including content from multiple repos, each of which has it's own version. |
|
Yes, @ihostage. Any comments or suggestions? |
@rstento No, only respect of this choice 😉 My suggestion (#104 (comment)) of using Antora wrote on 17 Sep 2019 when James created this issue 😂 |
|
Per language support docs set up for markdown/paradox and then converted to asciidoc/antora now. |
Eventually, all or most of the language specific support libraries may live in other repos, with Go likely being the first to do this, as discussed in #103. This raises a question for the docs. In an ideal world, documentation should live in the same repository as the code it documents, since updating documentation when a feature is added or changed should be part of the definition of done of a task, and PRs shouldn't be merged until the feature is done. It also allows things like code snippet validation to capture breaking changes before they are committed, and guarantee that if the breaking change is acceptable, the docs get updated since CI doesn't pass without it. But right now our approach to the docs is in a mono structure, with a single paradox project, and this also has a lot of advantages.
I think splitting up the docs will probably be the best answer long term, this will mean coming up with a way to deploy the docs that allows them to be split across repos. It might mean instead of deploying the docs to a single repo (replacing the entire contents of the repo each time), we deploy them to a subdirectory within a shared repo. We currently use travis's GitHub pages deployment support to deploy docs, that probably won't work, but we can easily replace this with our own custom scripts.
The text was updated successfully, but these errors were encountered: