[doc] Contribute user manual, installation guide and developer guide

Signed-off-by: Mélanie Bats <melanie.bats@obeo.fr>

.github/workflows/doc-gen.yml

@@ -0,0 +1,49 @@
+name: Deploy static documentation on Pages
+
+on:
+  push:
+    paths:
+      - "doc/**"
+    branches:
+      - "**"
+    tags:
+      - "*"
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Run Doc generation script
+        run: doc/generate.bash
+
+      - name: Fix permissions
+        run: sudo chmod -c -R +rX 'doc/docs-site/build'
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: 'doc/docs-site/build/site/'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

CHANGELOG.adoc

@@ -49,7 +49,7 @@ A reset of the database is needed.
 === Bug fixes
 
 - https://github.com/eclipse-syson/syson/issues/298[#298] [metamodel] Fix metamodel to manage root namespaces.
-- https://github.com/eclipse-syson/syson/issues/329[#329] [services] Ignore root namespace with no name during qualified name resolution 
+- https://github.com/eclipse-syson/syson/issues/329[#329] [services] Ignore root namespace with no name during qualified name resolution
 - https://github.com/eclipse-syson/syson/issues/337[#337] [diagrams] Fix direct edit of single digit cardinalities.
 - https://github.com/eclipse-syson/syson/issues/348[#348] [diagrams] The semantic representation of the Succession edge is not correct.
 - https://github.com/eclipse-syson/syson/issues/356[#356] [action-flow-view] The Allocate edge is not displayed in the Action Flow View diagram.
@@ -80,7 +80,7 @@ But, if you encounter execution rights problem, you can still copy _syside-cli.j
 
 === New features
 
-- https://github.com/eclipse-syson/syson/issues/315[#315] [tests] Add Cypress test infrastructure and execute the Cypress tests as part of pull request checks 
+- https://github.com/eclipse-syson/syson/issues/315[#315] [tests] Add Cypress test infrastructure and execute the Cypress tests as part of pull request checks
 - https://github.com/eclipse-syson/syson/issues/358[#358] [diagrams] Handle the JoinNode concept in actions body of diagrams
 - https://github.com/eclipse-syson/syson/issues/359[#359] [tests] Add tests to enforce a set of conventions on SysON DiagramDescriptions
 - https://github.com/eclipse-syson/syson/issues/371[#371] [diagrams] Handle the ForkNode concept in actions body of diagrams
@@ -91,6 +91,7 @@ But, if you encounter execution rights problem, you can still copy _syside-cli.j
 - https://github.com/eclipse-syson/syson/issues/423[#423] [diagrams] Add new documentation compartment on all existing nodes in all diagrams.
 - https://github.com/eclipse-syson/syson/issues/420[#420] [diagrams] Handle AssignmentAction concept in actions body in diagrams
 - https://github.com/eclipse-syson/syson/issues/405[#405] [tests] Add integration test infrastructure
+- [doc] Initial contribution of the documentation
 
 == v2024.5.0
 
@@ -109,7 +110,7 @@ But, if you encounter execution rights problem, you can still copy _syside-cli.j
 - https://github.com/eclipse-syson/syson/issues/144[#144] [diagrams] Fix an issue where the "Add existing elements (recursive)" failed on PartUsage.
 - https://github.com/eclipse-syson/syson/issues/167[#167] [interconnection-view] Add attributes compartment in children PartUsage nodes.
 - https://github.com/eclipse-syson/syson/issues/174[#174] [details] Fix an issue where an error raised when setting a valid new value (with primitive type) in the Details view.
-- https://github.com/eclipse-syson/syson/issues/192[#192] [import] Fix an issue where the /* and */ of a Comment's body were imported while importing a textual SysML file. 
+- https://github.com/eclipse-syson/syson/issues/192[#192] [import] Fix an issue where the /* and */ of a Comment's body were imported while importing a textual SysML file.
 - https://github.com/eclipse-syson/syson/issues/188[#188] [import] Fix an issue where some Memberships were contained in their parent through `ownedRelatedElement` instead of `ownedRelationship` reference.
 - https://github.com/eclipse-syson/syson/issues/184[#184] [import] Fix an issue from element imported threw an alias
 - https://github.com/eclipse-syson/syson/issues/249[#249] [import] Fix an issue to avoid Infinite Loop
@@ -151,7 +152,7 @@ But, if you encounter execution rights problem, you can still copy _syside-cli.j
 - https://github.com/eclipse-syson/syson/issues/151[#151] [diagrams] Add "Become nested" edge tools for AttributeUsage, ItemUsage, PartUsage and PortUsage.
 - https://github.com/eclipse-syson/syson/issues/154[#154] [diagrams] Add creation node tools inside existing usage elements.
 - https://github.com/eclipse-syson/syson/issues/163[#163] [diagrams] Add composite edges between usage and compartment content
-- https://github.com/eclipse-syson/syson/issues/165[#165] [general-view] Handle OccurrenceDefinition and OccurrenceUsage in General View diagram 
+- https://github.com/eclipse-syson/syson/issues/165[#165] [general-view] Handle OccurrenceDefinition and OccurrenceUsage in General View diagram
 - https://github.com/eclipse-syson/syson/issues/177[#177] [diagrams] Add reconnect tools for composition edges
 - https://github.com/eclipse-syson/syson/issues/180[#180] [diagrams] Handle Allocation definition and Allocation usage
 - https://github.com/eclipse-syson/syson/issues/196[#196] [export] SysML standard serialization format
@@ -219,7 +220,7 @@ They will be only accessible through the model browser dialog.
 - https://github.com/eclipse-syson/syson/issues/97[#97] [explorer] Add a filter allowing to hide membership elements in the Explorer view.
 - https://github.com/eclipse-syson/syson/issues/98[#98] [explorer] Add filters allowing to hide KerML/SysML libraries in the Explorer view.
 - https://github.com/eclipse-syson/syson/issues/93[#93] [diagrams] Add the following new diagrams:
-  * Action Flow view 
+  * Action Flow view
   * Requirement view
 - https://github.com/eclipse-syson/syson/issues/140[#140] [import] It is now possible to import SysMLv2 textual files into SysON, through the existing document upload modal.
 

doc/.vale.ini

@@ -0,0 +1,16 @@
+StylesPath = styles
+
+MinAlertLevel = warning
+
+Packages = Microsoft, Google, RedHat,  proselint, write-good, alex, Readability, Joblint
+
+[*.adoc]
+BasedOnStyles = Vale, Microsoft, Google, RedHat, proselint, write-good, alex, Readability, Joblint
+
+### Deactivate individual rules ###
+# Style1.Rule1 = NO
+Joblint.DevEnv = NO
+RedHat.Contractions = NO
+RedHat.Spelling = NO
+Vale.Spelling = NO
+write-good.E-Prime = NO

doc/Dockerfile

@@ -0,0 +1,44 @@
+FROM alpine:latest AS BUILD
+
+RUN apk add npm
+
+WORKDIR /usr/app
+
+COPY doc-ui /usr/app
+
+RUN npm install
+RUN ./node_modules/gulp/bin/gulp.js bundle
+
+FROM alpine:latest AS UI
+
+COPY --from=BUILD /usr/app/build/ui-bundle.zip /usr/app/ui-bundle.zip
+
+
+FROM alpine:latest
+
+RUN apk add git
+RUN apk add npm
+RUN apk add ruby ruby-dev gcc g++ make
+
+RUN mkdir /home/antora
+
+WORKDIR  /home/antora
+
+COPY docs-site/package.json .
+COPY docs-site/package-lock.json .
+
+RUN npm install
+RUN gem install asciidoctor
+RUN gem install asciidoctor-pdf
+RUN gem install rouge
+RUN gem install kramdown-asciidoc
+
+RUN apk del ruby-dev gcc g++ make
+
+ENV PATH="$PATH:/home/antora/node_modules/@antora/cli/bin/"
+
+COPY --from=UI /usr/app/ui-bundle.zip .
+
+WORKDIR /usr/app
+
+CMD ["antora", "--clean", "--stacktrace", "--log-level=all", "/usr/app/doc/docs-site/antora-playbook.yml"]

doc/content/README

@@ -0,0 +1,34 @@
+# Documentation best practices
+
+One sentence per line.
+Use asciidoc attributes to reference elements of the application UI.
+Use asciidoc attributes to reference URL.
+For reference to menus, key on the keyboard... use `backticks`.
+Use + on new line in table to force a new line
+
+
+Decide what you are saying and how: Define the kind of narrator, your tone and your mood
+Repeat yourself: a tutorial will have a brief introduction to what you’re going to do, then the actual procedure, and finally a way for you to verify that you’ve done the thing correctly
+Avoid using demonstrative pronouns: Instead of saying “this” or “that,” you should add a noun to spell out exactly what you’re referring to.
+Simplify: strive to get to the point as quickly as possible
+When writing instructions, anywhere you say “You/We should X” or “You/we can X,” replace it with the imperative mood of the verb.
+Instead of using constructions with “of” or “for,” rewrite the sentence to put more information before the noun.
+Break up long sentences into multiple shorter sentences.
+Eliminate passive voice
+Don’t use adverbs
+Don’t assume knowledge : Spell out acronyms on first use. Add a phrase or a sentence briefly explaining a concept when you introduce it. Link out to further reading.
+Be aware of your tone
+Avoid jargon and cliches
+Make use of whitespace
+
+# Vale
+We use vale, it is a linter for prose
+
+# Antora use
+* Ensure that docker is launch
+## on linux
+* Launch the script SysON\doc\generate.bash in a terminal
+## on Windows
+* Lunch the script SysON\doc\local-generation.ps1 in a Windows Power shell console
+## Result
+* Generation result is available in SysON\doc\docs-site\build\site

doc/content/antora.yml

@@ -0,0 +1,38 @@
+name: syson
+title: SysON
+version: true
+nav:
+  - modules/ROOT/nav.adoc
+
+asciidoc:
+  attributes:
+    afv: "Action Flow View"
+    bug-url: "https://github.com/eclipse-syson/syson/issues"
+    changelog-url: "https://github.com/eclipse-syson/syson/blob/main/CHANGELOG.adoc"
+    details: "Details"
+    diag-toolbar: "Contextual Toolbar"
+    editor: "Project Editor"
+    explorer-filter-bar: "Project Explorer Filter Bar"
+    explorer-menu: "Element Options Menu"
+    explorer: "Project Explorer"
+    forum-url: "https://github.com/eclipse-syson/syson/discussions"
+    gv: "General view"
+    homepage: "Projects Browser"
+    iv: "Interconnection view"
+    kerml: "KerML"
+    mbse: "Model-Based Systems Engineering"
+    packages-url: "https://github.com/eclipse-syson/syson/packages/2020337/versions"
+    product: "SysON"
+    product-jar: "org.eclipse.syson.syson-application-YYYY.M.X.jar"
+    projects-list: "Projects List"
+    projects-list-menu: "Project Options Menu"
+    related-elements: "Related Elements"
+    representations-view: "Representations"
+    source-code-url: "https://github.com/eclipse-syson/syson"
+    stv: "State Transition view"
+    sysml: "SysML"
+    sysmlv1: "{sysml} v1"
+    sysmlv2: "{sysml} v2"
+    sw: "Sirius Web"
+    validation: "Validation"
+    website-url: "https://eclipse.dev/syson/"

doc/content/modules/ROOT/README

@@ -0,0 +1,6 @@
+Recommended; Reserved
+
+Directory that contains the ROOT module.
+This special directory does not appear in the output path.
+Instead, it becomes the parent folder of any additional, named modules that you create in a component.
+The directory name must be written in all uppercase letters.

doc/content/modules/ROOT/assets/README

@@ -0,0 +1,3 @@
+Optional; Reserved
+
+Directory where multimedia and supplemental files are organized by content type.

doc/content/modules/ROOT/assets/attachments/README

@@ -0,0 +1,3 @@
+Optional; Reserved
+
+Directory that contains supplemental materials, such as PDFs or ZIP files, that readers can download via a link created in a page using the AsciiDoc link macro.

doc/content/modules/ROOT/assets/images/README

@@ -0,0 +1,3 @@
+Optional; Reserved
+
+Directory that contains pictures, screenshots, diagrams, and other graphics files that are displayed in a page using the AsciiDoc image macro.