Hi Thomas,
Sounds really interesting.
I'd view the docs issues slightly differently: what are our biggest pain
points and what should be the first incremental steps to solve those?
I think the biggest pain points (and thus biggest bang for buck) are:
_*1. How to build and release the existing docs / website is not well
documented*_
There is not a good web-page describing how one would build the docs
locally (e.g. to test it), or a good web-page saying how to release this
to make it go live. Writing a page that describes the current process
would greatly improve things. [if there is already, apologies and please
point me at it!]
Thomas, I believe you previously created a docker container for building
the docs (with the right jekyll version etc) - is that right? Can you
point us at that please?
_*2. Simplify releasing the docs (manually)*_
Switching to .asf.yaml sounds good. Could we do this now, before we
switch to vuepress?
It feels like this would not be too much work to document / set up, and
a lot of this would be reusable when/if we switch to vuepress.
I think setting this up so it can be done manually would be a
pre-requisite before trying to automate it in CI/jenkins, so is worth
doing first.
---
_*Affect on Downstream Projects*_
I know of at least one downstream project that embeds the brooklyn docs
within its own docs - I know that switching to vuepress would impact
that. We should be slightly conservative about changes to the docs
system. But saying that, this should not force us to stick with old tech
stacks - it's not as strict as an API contract!
Perhaps the first step for vuepress would be a spike, or sharing some
more examples - giving us a better idea about the total effort required,
and thus letting downstream projects know when it would be likely to
land and what the new system would look like.
_*Alternatives to vuepress?*_
Can anyone else comment on pros/cons and alternatives? I'm not familiar
enough with the docs domain to say whether vuepress is the best choice.
It sounds like a much better choice than the current tech, but I don't
know what the plausible alternatives are.
vuepress github repo [1] looks promising: 15.2k stars, 281 contributors,
1820 commits since April 2018, and 8 commits in the last 30 days from 8
different people.
[1] https://github.com/vuejs/vuepress
On 07/01/2020 09:58, Thomas Bouron wrote:
Hello Brooklyners, and welcome into this new decade! (i.e. Happy New Year!)
To start off nicely, I would like to make a proposal regarding the Brooklyn
website/doc.
*Background*
Currently, we have 2 separate projects in `brooklyn-docs`:
- the docs are using `gitbooks` and sources live in the `master` branch.
- the rest of the website is using an ancient version `Jekyll` and sources
live in the `website` branch.
We did this because:
1. the ancient version of Jekyll requires a very specific version of ruby
which is a pain to setup locally and on the CI. Meaning it was virtually
impossible to contribute the docs alone.
2. if there is a change in the docs, it didn't make sense to update the
website part and vice-versa.
3. we wanted to automatically publish the changes live as soon as PRs were
merged.
*Issue*
The problem with this approach is that we need to have 2 CI jobs to build 2
different parts and to somehow push these live. We never managed to
automatically publish updates to website/docs through Jenkins.
We also picked a tool that is unfortunately not maintained anymore
(gitbooks) as their team is pushing for a commercial offering. Our Jekyll
setup is very old and impossible to upgrade currently, as it's using custom
plugins that would need to be rewritten.
And finally, our setup is, in my view, way too complicated and clunky to
use.
*Proposal*
I took a look at different solutions and found one that seemed to tick all
the boxes, it's called vuepress [1] and let us to:
- reconciled the website and docs under the same branch as it supports
multiple layouts, hence build both in one go.
- have a custom navigation, based on whatever configuration we write.
- defined custom blocks that can use hardcoded HTML or vue templates (we do
have custom blocks for the blueprint tours, tips, alerts, etc...)
- have custom search like gitbooks + be responsive and SEO friendly.
- have a toolchain that is maintained, open source and easy to use.
On top of that, having the full website build in one go will enable us to
push, from Jenkins, the compiled files to another branch (like `asf-pages`)
and leverage a new service called `.asf.yaml` [2] which takes care of
publishing it.
WDYT?
Best.
[1] https://vuepress.vuejs.org/
<https://vuepress.vuejs.org/guide/#how-it-works>
[2]
https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=127405038#id-.asf.yamlfeaturesforgitrepositories-WebSiteDeploymentServiceforGitRepositories
