bonitasoft / bonita-documentation-site Goto Github PK
View Code? Open in Web Editor NEWThe sources of the Bonita Documentation site
Home Page: https://documentation.bonitasoft.com/
License: GNU General Public License v2.0
The sources of the Bonita Documentation site
Home Page: https://documentation.bonitasoft.com/
License: GNU General Public License v2.0
For now, we can
When a PR is created on the documentation content repository, the documentation site (at least the part containing the change - component branch) is built and made available on a public site.
If possible
A lot of solutions exist to host static site: heroku, netlify, https://surge.sh/, vercel, ...
See also #49 to see if we can have a shared solution for both use cases.
https://github.com/bonitasoft/bonita-openapi provides an OpenAPI file that can be used to generate the REST API documentation.
We would like to remove the manually maintained REST API documentation from the Bonita documentation and replace it by a new documentation section generated from the OpenAPI resources.
To be discussed
Prior starting the real 'put the site live', the branches (except the ones related to product version - so feature branches) still using the markdown syntax must be managed.
There are a lot of old branches still alive. For instance, on 2021-01-13, there are 47 branches in bonita-doc (https://github.com/bonitasoft/bonita-doc/branches/all)
Some of them cannot be deleted for now, because there are considered as protected because of a branch pattern that is not restrictive enough (we only want to protect branches that exactly match product versions).
For branches related to opened PR, we can ask people to merge them prior the migration. Otherwise, they will have to recreate them or migrate them manually.
Let's start with the assumption that it will be Elastic as Service to compare
Currently, after each changes and rebuild from the https://github.com/bonitasoft/bonita-documentation-theme we want to use in the documentation site, we have to store the new zip file in the repository.
Let's check if we can store it in a remote storage and retrieve it when generating the site.
See also https://docs.antora.org/antora/2.3/playbook/ui-bundle-url/
Potential targets
Tasks
During the initial BICI conversion (#17), we have detected that the tables in the rest api documentation were not correctly migrated, but those in the prerequisites page were correctly converted.
This may be an issue in the md sources: the rest api md files are generated, so maybe the syntax is not fully correct, the old generation system is able to convert them but not kramdoc.
So we have to be careful when doing conversion review for pages that contain tables.
The content of this repository can be migrated right now
Tasks
master
branch from 1.3 and migrate content, see bonitasoft/bonita-labs-doc#118Note
Once this is done, the content of the repository will be updated by content contributors.
This will
The kramdoc tool is unable to convert asciinema content and generates error, for instance, with file like Bonita migrate-from-an-earlier-version-of-bonita-bpm.md
<script type="text/javascript">
function loadCSS(filename){
let file = document.createElement("link");
file.setAttribute("rel", "stylesheet");
file.setAttribute("type", "text/css");
file.setAttribute("href", filename);
document.head.appendChild(file);
}
loadCSS("./assets/asciinema-player.css");
</script>
<asciinema-player src="bonita/images/${varVersion}/case_overview_update_mode-ascii.cast" speed="2" theme="monokai" title="Update case overview console output example" cols="240" rows="32"></asciinema-player>
<script src="./assets/asciinema-player.js"></script>
Workaround for the conversion procedure
/
characters by +
(you should have some ++++
at the end of the block a)modules/ROOT/assets/attachments
and copy the asciinema-player.js et asciinema-player.css that are currently only available in the private documentation site gnerator repositoryNew Investigations to be conducted
Tasks (to be extended depending on the chosen solution)
Initialize bonita-documentation-theme with https://github.com/alachambre/antora-ui
A global schema should be nice
To be reviewed with final decision
Talk with IT to manage the real switch (Who /when/how)
Rationale: the documentation site will be available at https://bonitasoft.github.io/ during development in parallel to https://documentation.bonitasoft.com/. We want to avoid duplicated content detection by search engine.
See https://docs.antora.org/antora/2.3/playbook/site-robots/
Resources
Tasks
We should decide this before converting to much documentation content branches, otherwise we will have to go back to the branches afterwards.
Each repository and each branches in the repository duplicates some information that are out-of-date and incomplete. Sometimes there is a link to see how to contribute (markdown tips and how-to) which confer to the Bonita 7.3
branch
At the same place, we have mixed information for Tech Writers and Developers
Centralize most information directly in the bonita-documentation-site
repository
In progress --> managed by #142
Modules allow to better separate content and resources (for instance specific images and
attachments). For Bonita doc, this will avoid for instance to have all "getting started" pages at
the same level as other pages (currently in the md foler): eaiser to identify what pages and images
are related to "getting started", easier maintenance, ....We won't be able to move to module right now as the url would changes but at least for new content
To keep in each repository and branch
The Antora Default UI provide a way to include Google Analytics script in all pages by just adding a conf entry in the Antora Playbook, see https://docs.antora.org/antora/2.3/playbook/site-keys/#google-analytics-key
Goal: explicitly inform users that they are using out-of-support versions and provide a link to the newest version
In the old documentation, this was sometimes done by changing the "Fork me on " rubber into "Out of support". On 2020-11-19
, this was only available in the Bonita 7.3
documentation
Using the rubber is not the best choice as we use the same design for 2 different things and users associate the rubber to a link for contributions, so don't pay attention to the "out of support" text.
Let's have a look to the solution provided by the Couchbase Antora UI project: a banner is added to the top of the page and provide a link to the latest available version.
We could use the same logic to have a banner with a warning. A out of support version could be configured in the doc content repository antora configuration file at branch/version level (as an asciidoctor attribute or any other available configuration)
In addition, we could update the display version like proposed in https://docs.antora.org/antora/2.3/component-display-version/#display-version-key: 7.7 EOL
See also #33
In the previous doc site, we were able to use variable in the documentation that were defined in a json file.
For instance, this is used by Asciinema resources - varVersion
(see also #29) or BCD used it to declare the Bonita version to target (bonitaDocVersion
, see bonitasoft/bonita-continuous-delivery-doc@7ed78d2).
Asciidoctor allows to configure custom properties/attributes in the page, let's check what Antora provides on this side.
For now we have warning when the variables are encountered:
asciidoctor: WARNING: skipping reference to missing attribute: varversion
Notice that we have warnings for elements considered as variables in the documentation, mainly in Bonita Rest API documentation
asciidoctor: WARNING: skipping reference to missing attribute: page
asciidoctor: WARNING: skipping reference to missing attribute: count
asciidoctor: WARNING: skipping reference to missing attribute: order
asciidoctor: WARNING: skipping reference to missing attribute: query
asciidoctor: WARNING: skipping reference to missing attribute: filter_name
asciidoctor: WARNING: skipping reference to missing attribute: filter_value
Tasks
$
character. It seems that javadoc links (they use the varVersion
attribute) are not generated correctly and contains a $
character. --> no, we have to remove itRemark: this is something similar to what we could need for #39.
The javadoc is currently available via url like http://documentation.bonitasoft.com/javadoc/api/7.11/index.html and is not part of the documentation content repository. It is pushed directly on the server.
Note: We also have groovy doc
359 MB
in 2a0a6fdAt 1st glance, the javadoc url could change as they are not supposed to be indexed so we shouldn't be forced to keep the original urls.
When we will have redirect capabilities (#117), we will be able to put redirect from old redirect to new one (or if needed, setup rewrite rules)
Note: this is independent of the choosen hosting solution
how do we set links to javadoc in the source documentation content. Currently, the url is hard coded and the version is managed via a variable (see also #54). We could use a single Asciidoctor attribute that contains the full url.
Possible implementation
docs.antora.org/antora/2.3/playbook/site-robots
Robots have been disallowed while setuping the new site, see #19
To be set in the robots.txt.
This will avoid potential content duplication between the new site (currently only available at https://bonitasoft.github.io/) and https://documentation.bonitasoft.com/
This may be useful if
TO BE DISCUSSED and probably tested
If possible, we could also only rebuild a single branch.
Rebuild all
In the gh-pages branch, commit/push only the component version (folder including the version) which has changed + probably the related sitemap file
We could also detect the changed asciidoctor source file and only commit the related html file
Investigations
Tasks if we want to do it
In the old documentation site, the Bonita 7.2 and before documentation version is displayed in the version pick list as shown in the above screenshot.
When clicking on such versions, a modal is displayed and the user is redirected to the Legacy documentation website
We don't have this by default with Antora UI so we can
See also #33.
Antora Resources that may help
Improvement of #5
We would like to have this information to be able to detect which documentation content component triggers a build.
This will allow us to have a better message when committing to the gh-pages
branch and let us track the reason of the commit.
In the future, we may also be able to only rebuild the component that is passed as inputs of the request (see #46).
Add inputs to the workflow_dispatch configuration (see #5 for repositories we used to poc such a solution)
Commit messages
deploy <commit>
as todaydeploy <commit> from manual request
deploy <component> <branch> update
package.json
file. See #28gh-pages
branch to better track what changes in production. Notice that #45 will also help to have a better trackingSee also #46 for more details.
We already have identified that the sitemap files are going to be updated very often if we rebuild the whole site. For instance
We currently (f599811) always clean the Antora build directory when building locally and GitHub Workflow always use a fresh environment, so we don't keep any previous generated files.
We may test if keeping previously generated files change the way the sitemap are generated.
If so, for the GitHub actions, we may keep a cache for the master branch
In current site, there is a release notes pages that is duplicated accross all bonita doc supported versions.
This require branch merges and maintenance which is a pain.
With the new documentation powered by Antora, we could have a dedicated migration tool section for displaying release notes, backed by
migration
component with no versionWe are going to published the generated static sites to GitHub pages.
We can start doing this prior configuring automation with #5
In the old documentation site, the index/home page of each component were using inline html content directly in the markdown source.
For now, this content cannot be converted correctly into Asciidoctor automatically. This problem is documented in the conversion step documentation initiated with #17
This is what the old site currently displays
Bonita | Bonita Cloud |
---|---|
BCD | BICI |
---|---|
Couchbase doc home page with a kind of tables
If we don't put redirect rules, we must ensure that urls stay the same to avoid any mess with Search Engine like Google.
See also #24
Documentation that could use version-less/master version (https://docs.antora.org/antora/2.3/component-with-no-version/#version-master):
In case we have to keep the original url but we do want use 'no version' Antora component:
Everything is managed in the documentation site generator project.
Antora Default UI features
Proposition 1: keep the existing behaviour
Possible extension in Antora UI if we want to keep
in the nav-explore.hbs
, the version list accesses to the component version elements. We could hide a prerelease version that has custom attributes/properties (if it can access to it, these elements can be configured in the antora config file in the component documentation repository) or if the displayed version contains a specific string (preview, dev).
Proposition 2: switch to Antora default
Is this really a problem to make the documentation of a preview/dev version visible to everybody.
In the old site, we could use https://documentation.bonitasoft.com/bonita/latest/ or https://documentation.bonitasoft.com/bcd/current/ (in fact, any string instead of a version) and we were reaching the latest version of the component documentation.
Let's see if we can do the same with the new site.
Generally, this is manage with a redirect rule configured in the http server. It seems that the Couchbase doc has implementated something in the antora ui/theme part to provide something on that field: see https://github.com/couchbase/docs-ui/blob/v269/README.adoc#view-latest-and-canonical-url
latest
instead of named version for the newest supported versionIf we can have a redirect of latest to a named version we could do the following example
latest
and the displayed version 7.12
: the url contains latest instead of
7.12` and the pages display the expected version7.12
and is then available with the 7.12 urlslatest
, and the neweset version is then available through the latest
urlThis requires more work on Product GA and we should see if we have issues on the SEO side.
Setup Github action to:
when
A poc has been done with 2 repositories to manage triggering a workflow stored in a repository from workflow located in another repository
For site generation and push to gh-pages in a GitHub workflow, we can have a look at https://github.com/process-analytics/bpmn-visualization-js/blob/v0.7.0/.github/workflows/generate-documentation.yml
Do we run a build when the master branch of this repo is updated
probably yes to ensure new theme or antora playbook changes are used
Should not been run on documentation changes (use exclude path)
Do we run a build when PR targeted master are created?
In that case, we could build the site with the local profile and attach it as workflow artifacts. The resulting site could be then tested locally after having been downloaded
In the future, we could deploy the generated site on a public free solution (netlify, vercel, heroku, ...)
In the current documentation site, out-of-support versions are in a submenu of the versions list of a component.
We don't have this by default with Antora UI but we also expect to be able to better identify pages related to out-of-support versions, see also #22.
We should decide if
7.7 EOL
)Note: to be implemented only if decided in #21
In the old documentation solution, this done by a private CI.
This could be done by Github Actions on each content documentation repository
Initialize this repo with work done on https://github.com/alachambre/antora-playbook-test
The production site is deployed on GitHub pages which only provide a single 'production' environment.
When we create a PR to change the site structure (Antora UI, Antora playbook configuration), we currently can only tests the resulting generated site by downloading an artifact and open it locally.
But this is not very convenient to test changes on mobile: we have to expose the site through a local server.
Having a preview live environment would allow to test mobile easily, share an url for quick evaluation by anyone without having to setup anything.
See also #50 to see if we can have a shared solution for both use cases.
In the old documentation site, it was possible to use font awesome icons.
For instance the BICI index page uses icon with links to release-notes, getting started, ... (https://github.com/bonitasoft/bonita-ici-doc/blob/1bfba7e81f38250e568a5b1a4f29b4b6125f6215/md/index.md)
Same for BCD (https://github.com/bonitasoft/bonita-continuous-delivery-doc/blob/0538a65330f0058f5b3c5f36c3199c0e42529b03/md/index.md)
Same for Bonita Cloud (https://github.com/bonitasoft/bonita-cloud-doc/blob/cf6c2e6d478b40a5ce688d6f76a4b945a7241b82/md/index.md)
Providing icons support helps the documentation to be more attrative, so we should check what we can provide on this side.
This is possible with Asciidoctor (https://asciidoctor.org/docs/user-manual/#icons). See what is possible with Antora.
This may be related to #66
[UPDATE 2022-01-10] https://antora.zulipchat.com/#narrow/stream/282400-users/topic/.E2.9C.94.20font.20awesome. It should work as in a regular AsciiDoc page: declare the icon set as AsciiDoc attribute and use the icon macro: https://docs.asciidoctor.org/asciidoc/latest/macros/icons/
This at least applies to bonita-doc
The current way of fixing/updating the documentation is to perform the change in the oldest supported version, then merge the branch from version to version to propagate the change.
This process is automated using a private solution hosted by Bonitasoft (private CI and private scripts).
Do we continue to do it privately or do we setup a public CI job to manage it?
If we decide to switch to GitHub Actions, implement #12
Defects:
Various documentation generated with Antora adds icons in Admonitions generated by the Antora default UI bundle
kroki also uses Antora, they have put additional icons to NOTE, WARNING, .... https://docs.kroki.io/kroki/setup/usage/ https://docs.kroki.io/kroki/setup/kroki-cli/
The asciidoc and asciidoctor official documentation using Antora also display icons, for instance on https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/
This example provides a way to customize Admonicon without changing the Antora UI bundle: https://blog.yuzutech.fr/blog/antora-admonitions-icons/index.html.
This will cover a part of #6
See https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/configuring-a-custom-domain-for-your-github-pages-site
Questions
What conventions do we want to use:
Once dediced
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.