diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 410e9ed7c2..ae80e99454 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,17 +25,17 @@ If you start working on one of the existing [issues](https://github.com/process- 3. Do not commit changes to files that are irrelevant to your feature or bugfix (eg: `.gitignore`). -4. Provide [tests](./docs/development/development.md#tests) and documentation whenever possible. +4. Provide [tests](./docs/contributors/development.md#tests) and documentation whenever possible. -5. Be sure you have followed the [code style](./docs/development/development.md#code-style) for the project. +5. Be sure you have followed the [code style](./docs/contributors/development.md#code-style) for the project. 6. Prior opening a Pull Request, ensure the build is fully working by locally running `npm run all` (build, check and test everything) -7. Open a [GitHub Pull Request](./docs/development/pull-request.md#open-a-pull-request) with your patches. (**1** pull request = **1** feature or bug) +7. Open a [GitHub Pull Request](./docs/contributors/pull-request.md#open-a-pull-request) with your patches. (**1** pull request = **1** feature or bug) We will review your contribution and respond as quickly as possible. Keep in mind that this is an open source project, and it may take us some time to get back to you. Your patience is very much appreciated. -8. If this is your 1st Pull Request, sign the [Contributor License Agreement](./docs/development/pull-request.md#sign-the-contributor-license-agreement) +8. If this is your 1st Pull Request, sign the [Contributor License Agreement](./docs/contributors/pull-request.md#sign-the-contributor-license-agreement) 9. Be willing to accept criticism and work on improving your code. @@ -54,11 +54,11 @@ git checkout -b 25-annotations_to_tasks ``` ### IDE configuration -To know how configurate your development environment, see [IDE configuration](./docs/development/ide-configuration.md). +To know how configurate your development environment, see [IDE configuration](./docs/contributors/ide-configuration.md). ### Development -You'll find [here](./docs/development/development.md) the necessary information to build, test, lint your code, and some tips too. +You'll find [here](./docs/contributors/development.md) the necessary information to build, test, lint your code, and some tips too. ### Commit in your branch There is no convention for the commit message in your branch. @@ -69,11 +69,11 @@ The most important part is the title of the Pull Request, because: ### Pull Request -After your development finished, you need to open a Pull Request. You'll find [here](./docs/development/pull-request.md) all the necessary information to open it and to keep it updated. +After your development finished, you need to open a Pull Request. You'll find [here](./docs/contributors/pull-request.md) all the necessary information to open it and to keep it updated. At this point, you're ready to make your changes! Feel free to ask for help. Everyone is a beginner at first 😸 ## Maintainers -See the necessary information for the [Maintainers](./docs/development/maintainers.md) +See the necessary information for the [Maintainers](./docs/contributors/maintainers.md) diff --git a/README.md b/README.md index 192ad59355..26b60b2c12 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@

BPMN Visualization

-

+

npm package @@ -127,7 +127,7 @@ You can find more detail in our [Contributing guide](CONTRIBUTING.md). Participa `bpmn-visualization` is released under the [Apache 2.0](LICENSE) license. \ Copyright © 2020, Bonitasoft S.A. -Some BPMN icons used by `bpmn-visualization` are derived from existing projects. See the [BPMN Support page](docs/bpmn-support.adoc) +Some BPMN icons used by `bpmn-visualization` are derived from existing projects. See the [BPMN Support page](docs/users/bpmn-support.adoc) for more details: - [draw.io](https://github.com/jgraph/drawio) (Apache-2.0) - [flaticon](https://www.flaticon.com) ([freepikcompany license](https://www.freepikcompany.com/legal#nav-flaticon)) diff --git a/docs/contributors/README.md b/docs/contributors/README.md new file mode 100644 index 0000000000..c7bb37b890 --- /dev/null +++ b/docs/contributors/README.md @@ -0,0 +1,22 @@ +# Guidelines for Contributors and Development + +General information are available in the [Contributing Guide](../../CONTRIBUTING.md). +Information about the library internals are available in the [architecture folder](../users/architecture) or in html form in the [documentation site](https://process-analytics.github.io/bpmn-visualization-js/#_architecture_and_development) + +Here are some tips to help during development. + +## Build and develop + +- [how to build & code style](development.md) +- [IDE configuration](ide-configuration.md) + +## Contributing +- [testing](testing.md) +- [how to support new BPMN elements](bpmn-support-how-to.md) +- [how to submit your work](pull-request.md) +- [mxgraph integration](mxgraph-integration.md) +- [mxgraph version bump](mxgraph-version-bump.md) + +## Misc +- [documentation guidelines](documentation-guidelines.md) +- [for the maintainers](maintainers.md) diff --git a/docs/development/bpmn-support-how-to.md b/docs/contributors/bpmn-support-how-to.md similarity index 96% rename from docs/development/bpmn-support-how-to.md rename to docs/contributors/bpmn-support-how-to.md index 10b0665e3b..0555d97b8b 100644 --- a/docs/development/bpmn-support-how-to.md +++ b/docs/contributors/bpmn-support-how-to.md @@ -44,12 +44,12 @@ Refer to existing Pull Requests to have a better view about the work to do, for When changing the model, the image representing the model in the documentation needs to be updated as well. The documentation uses the SVG image produced from draw.io file. -This file is stored [here](../architecture/images/architecture/internal-model.drawio). +This file is stored [here](../users/architecture/images/architecture/internal-model.drawio). To update the model -- edit [internal-model.drawio](../architecture/images/architecture/internal-model.drawio) with https://app.diagrams.net or with the `diagrams.net` desktop application +- edit [internal-model.drawio](../users/architecture/images/architecture/internal-model.drawio) with https://app.diagrams.net or with the `diagrams.net` desktop application - store the modified file in the repository -- don't forget to export it as SVG and store it in [the repository](../architecture/images/architecture/internal-model.svg) as well +- don't forget to export it as SVG and store it in [the repository](../users/architecture/images/architecture/internal-model.svg) as well ### What to change? diff --git a/docs/development/development.md b/docs/contributors/development.md similarity index 88% rename from docs/development/development.md rename to docs/contributors/development.md index 1b47bbbb55..55ce6f5f27 100644 --- a/docs/development/development.md +++ b/docs/contributors/development.md @@ -1,8 +1,8 @@ # Development **Note**: -- information about the library internals are available in the [architecture folder](../architecture) or in html form in the [documentation site](https://process-analytics.github.io/bpmn-visualization-js/#_architecture_and_development) -- additional information related to development can also be found in the [development details page](.//README.md) +- information about the library internals are available in the [architecture folder](../users/architecture) or in html form in the [documentation site](https://process-analytics.github.io/bpmn-visualization-js/#_architecture_and_development) +- additional information related to development can also be found in the [contributors guidelines page](./README.md) ## Requirements diff --git a/docs/development/documentation-guidelines.md b/docs/contributors/documentation-guidelines.md similarity index 87% rename from docs/development/documentation-guidelines.md rename to docs/contributors/documentation-guidelines.md index 079be8cf0e..06ca61c352 100644 --- a/docs/development/documentation-guidelines.md +++ b/docs/contributors/documentation-guidelines.md @@ -2,13 +2,13 @@ Below guidance should serve to write the properly distributed documentation and to avoid any duplications. Projects documentation consists of: -- HTML documentation - everything at the root of the docs/ folders and under /docs/architecture +- HTML documentation - everything under the /docs/users folder, with AsciiDoctor sources - High level information - Contextual content - BPMN support details - Architecture overview -- Markdown documentation for Developers / Integrators - all .md files in project root and under /docs/development +- Markdown documentation for Developers / Integrators - all .md files in project root and under /docs/contributors - Development guidance - How tos - Detailed usage diff --git a/docs/development/ide-configuration.md b/docs/contributors/ide-configuration.md similarity index 100% rename from docs/development/ide-configuration.md rename to docs/contributors/ide-configuration.md diff --git a/docs/development/images/bpmn-icon-example.png b/docs/contributors/images/bpmn-icon-example.png similarity index 100% rename from docs/development/images/bpmn-icon-example.png rename to docs/contributors/images/bpmn-icon-example.png diff --git a/docs/development/maintainers.md b/docs/contributors/maintainers.md similarity index 100% rename from docs/development/maintainers.md rename to docs/contributors/maintainers.md diff --git a/docs/development/mxgraph-integration.md b/docs/contributors/mxgraph-integration.md similarity index 100% rename from docs/development/mxgraph-integration.md rename to docs/contributors/mxgraph-integration.md diff --git a/docs/development/mxgraph-version-bump.md b/docs/contributors/mxgraph-version-bump.md similarity index 100% rename from docs/development/mxgraph-version-bump.md rename to docs/contributors/mxgraph-version-bump.md diff --git a/docs/development/pull-request.md b/docs/contributors/pull-request.md similarity index 100% rename from docs/development/pull-request.md rename to docs/contributors/pull-request.md diff --git a/docs/development/testing.md b/docs/contributors/testing.md similarity index 100% rename from docs/development/testing.md rename to docs/contributors/testing.md diff --git a/docs/development/README.md b/docs/development/README.md deleted file mode 100644 index c5b7fe42d6..0000000000 --- a/docs/development/README.md +++ /dev/null @@ -1,22 +0,0 @@ -# Development - -General information are available in the [Contributing Guide](../../CONTRIBUTING.md). -Information about the library internals are available in the [architecture folder](./docs/architecture) or in html form in the [documentation site](https://process-analytics.github.io/bpmn-visualization-js/#_architecture_and_development) - -Here are some tips to help during development. - -## Build and develop - -- [how to build & code style](./development.md) -- [IDE configuration](./ide-configuration.md) - -## Contributing -- [testing](./testing.md) -- [how to support new BPMN elements](./bpmn-support-how-to.md) -- [how to submit us your work](./pull-request.md) -- [mxgraph integration](./mxgraph-integration.md) -- [mxgraph version bump](./mxgraph-version-bump.md) - -## Misc -- [documentation guidelines](docs/development/documentation-guidelines.md) -- [for the maintainers](./maintainers.md) diff --git a/docs/architecture/00-index.adoc b/docs/users/architecture/00-index.adoc similarity index 100% rename from docs/architecture/00-index.adoc rename to docs/users/architecture/00-index.adoc diff --git a/docs/architecture/architecture-overview.adoc b/docs/users/architecture/architecture-overview.adoc similarity index 100% rename from docs/architecture/architecture-overview.adoc rename to docs/users/architecture/architecture-overview.adoc diff --git a/docs/architecture/bpmn-internal-model.adoc b/docs/users/architecture/bpmn-internal-model.adoc similarity index 100% rename from docs/architecture/bpmn-internal-model.adoc rename to docs/users/architecture/bpmn-internal-model.adoc diff --git a/docs/architecture/bpmn-parsing.adoc b/docs/users/architecture/bpmn-parsing.adoc similarity index 100% rename from docs/architecture/bpmn-parsing.adoc rename to docs/users/architecture/bpmn-parsing.adoc diff --git a/docs/architecture/development.adoc b/docs/users/architecture/development.adoc similarity index 83% rename from docs/architecture/development.adoc rename to docs/users/architecture/development.adoc index a86f978265..5427a6e37d 100644 --- a/docs/architecture/development.adoc +++ b/docs/users/architecture/development.adoc @@ -11,5 +11,5 @@ endif::[] [TIP] ==== - To know how to build the project, please have a look at the https://github.com/process-analytics/bpmn-visualization-js/blob/master/CONTRIBUTING.md[contributing guide]. -- For any development tips, see the https://github.com/process-analytics/bpmn-visualization-js/blob/master/docs/development[development documentation]. +- For any development tips, see the https://github.com/process-analytics/bpmn-visualization-js/blob/master/docs/contributors[development documentation]. ==== diff --git a/docs/architecture/images/architecture/architecture_overview.svg b/docs/users/architecture/images/architecture/architecture_overview.svg similarity index 100% rename from docs/architecture/images/architecture/architecture_overview.svg rename to docs/users/architecture/images/architecture/architecture_overview.svg diff --git a/docs/architecture/images/architecture/internal-model.drawio b/docs/users/architecture/images/architecture/internal-model.drawio similarity index 100% rename from docs/architecture/images/architecture/internal-model.drawio rename to docs/users/architecture/images/architecture/internal-model.drawio diff --git a/docs/architecture/images/architecture/internal-model.svg b/docs/users/architecture/images/architecture/internal-model.svg similarity index 100% rename from docs/architecture/images/architecture/internal-model.svg rename to docs/users/architecture/images/architecture/internal-model.svg diff --git a/docs/architecture/mxgraph-integration.adoc b/docs/users/architecture/mxgraph-integration.adoc similarity index 77% rename from docs/architecture/mxgraph-integration.adoc rename to docs/users/architecture/mxgraph-integration.adoc index 44f96fc216..67ce988c47 100644 --- a/docs/architecture/mxgraph-integration.adoc +++ b/docs/users/architecture/mxgraph-integration.adoc @@ -5,4 +5,4 @@ https://jgraph.github.io/mxgraph/docs/manual.html#3.1.1[mxGraph model] from the It also provides the Diagram Navigation support. -For more details, see the https://github.com/process-analytics/bpmn-visualization-js/tree/master/docs/development/mxgraph-integration.md[development documentation]. +For more details, see the https://github.com/process-analytics/bpmn-visualization-js/tree/master/docs/contributors/mxgraph-integration.md[development documentation]. diff --git a/docs/bpmn-support.adoc b/docs/users/bpmn-support.adoc similarity index 100% rename from docs/bpmn-support.adoc rename to docs/users/bpmn-support.adoc diff --git a/docs/images/bpmn-diagram_navigation_C.2.0.gif b/docs/users/images/bpmn-diagram_navigation_C.2.0.gif similarity index 100% rename from docs/images/bpmn-diagram_navigation_C.2.0.gif rename to docs/users/images/bpmn-diagram_navigation_C.2.0.gif diff --git a/docs/images/diagram-example.png b/docs/users/images/diagram-example.png similarity index 100% rename from docs/images/diagram-example.png rename to docs/users/images/diagram-example.png diff --git a/docs/images/diagram-hacktoberfest-example.png b/docs/users/images/diagram-hacktoberfest-example.png similarity index 100% rename from docs/images/diagram-hacktoberfest-example.png rename to docs/users/images/diagram-hacktoberfest-example.png diff --git a/docs/index.adoc b/docs/users/index.adoc similarity index 100% rename from docs/index.adoc rename to docs/users/index.adoc diff --git a/docs/intro.adoc b/docs/users/intro.adoc similarity index 100% rename from docs/intro.adoc rename to docs/users/intro.adoc diff --git a/docs/overview.adoc b/docs/users/overview.adoc similarity index 100% rename from docs/overview.adoc rename to docs/users/overview.adoc diff --git a/scripts/docs.js b/scripts/docs.js index e97e987aef..191b91aabb 100644 --- a/scripts/docs.js +++ b/scripts/docs.js @@ -28,10 +28,9 @@ console.info('Building bpmn-visualization html documentation'); fse.removeSync(docsOutput); // build html docs -Asciidoctor().convert(fs.readFileSync('docs/index.adoc'), { - base_dir: 'docs', - to_file: `../${docsOutput}/index.html`, - // to_file: '../build/docs/index.html', +Asciidoctor().convert(fs.readFileSync('docs/users/index.adoc'), { + base_dir: 'docs/users', + to_file: `../../${docsOutput}/index.html`, standalone: true, mkdirs: true, safe: 'unsafe', // needed because we want to generate the html outside of the directory that stores the source files @@ -40,8 +39,8 @@ Asciidoctor().convert(fs.readFileSync('docs/index.adoc'), { // copy images fse.ensureDirSync(`${docsOutput}/images`); -fse.copySync('docs/images', `${docsOutput}/images`); -fse.copySync('docs/architecture/images', `${docsOutput}/images`); +fse.copySync('docs/users/images', `${docsOutput}/images`); +fse.copySync('docs/users/architecture/images', `${docsOutput}/images`); fse.copySync('src/static/img/favicon.ico', `${docsOutput}/favicon.ico`); // eslint-disable-next-line no-console