chore(website): expose documentation on the website (#1511)

asyncapi · Oct 4, 2023 · 4175fbd · 4175fbd
1 parent bc69a9f
commit 4175fbd
Show file tree

Hide file tree

Showing 24 changed files with 2,987 additions and 47 deletions.
diff --git a/.gitignore b/.gitignore
@@ -7,7 +7,4 @@ lib
 output
 # Where the runtime testing for Java places node modules
 java_runtime_node
-*.log
-
-# API documentation
-modelina-website/public/docs/api/generated
+*.log
diff --git a/docs/README.md b/docs/README.md
@@ -48,18 +48,18 @@ Details which different generator options are supported.
 ### [Presets](./presets.md)
 Goes more in-depth into how the preset system works, which enables full customization of generators.
 
-### [Interpretation of JSON Schema](./inputs/JSON_Schema.md)
+### [Interpretation of JSON Schema](./inputs/json-schema.md)
 Explains how a JSON Schema is interpreted to a data model.
 
-### [Migration](./migration.md)
+### [Migration](./migrations/README.md)
 As time goes on, major versions are inevitable and expected! You can find the migration guides here.
 
 ### [Coming from other tools](./other-tools.md)
 Contains specific information about the differences between a lot of other common model generation tools. 
 
-### [API Documentation](https://modelina.org/docs/api)
+### [API Documentation](https://modelina.org/apidocs)
 
-No one wants to read the code to find information about it, instead use the [/docs/api](https://modelina.org/docs/api) page on the website to find what you are looking for!
+No one wants to read the code to find information about it, instead use the [/apidocs](https://modelina.org/apidocs) page on the website to find what you are looking for!
 
 ### Languages
 Each language has its own limitations, corner cases, and features; thus, each language has separate documentation.

diff --git a/docs/champions.md b/docs/champions.md
@@ -1,54 +1,63 @@
-
 <p align="center">
-  <img src="https://i.giphy.com/media/3ohs4Az5xSJj0RYrss/giphy.webp" width="300" height="300">
+  <img src="https://i.giphy.com/media/3ohs4Az5xSJj0RYrss/giphy.webp" width="300" height="300"/>
 </p>
 
 # Mission
 
 Modelina aims to be the number one library for generating models, allowing full customization to the user to forge their models from minimalist models to their hearts desire. We don't assume we know what all the users wants, we enable them to decide for themself.
 
 # Champions
+
 As Modelina grows, more and more people would like to become maintainers, each with varying degree of time to give.
 
 In order to have something for everyone, we introduce the concept of `champions` where we split up the areas of responsibility where best possible. Champions will have the ability to merge and accept pull requests for their [area of responsibility](#areas-of-responsibility), basically owning and maintaining a part of Modelina. This also entitles you to join the [AsyncAPI TSC](https://www.asyncapi.com/community/tsc).
 
 You can checkout the [CODEOWNERS file](../CODEOWNERS) for an updated list of maintainers and what areas they champion.
 
 ## Areas of responsibility
+
 These are the areas that we mainly focus on getting having champions and where you can help out. However, keep in mind it is not limited to these alone.
 
 ### :running: Core champions
+
 There is not one area that interest you, but rather the library as a whole, where you want to maintain and push forward the project and it's mission.
 
 ### :books: Doc champions
+
 Doc champions are those who focus on the documentation and how users best go from 0 to 100 in order to use Modelina. Maybe you like to write technical documentation, or you love making tutorials, this would be for you!
 
 ### :trident: Input champions
+
 Input champions are those who take charge of the input processing, it can either be a specific input processor (such as JSON Schema or AsyncAPI) or multiple. They maintain the process of converting the input to the internal model which Modelina can use to generate outputs to.
 
 ### :wrench: Language champions
-Language champions are those who maintain of a specific language output, it can either be a specific generator (such as TypeScript or Java) or or multiple. They maintain the process of converting the internal model into usable data models in their respective language. 
+
+Language champions are those who maintain of a specific language output, it can either be a specific generator (such as TypeScript or Java) or or multiple. They maintain the process of converting the internal model into usable data models in their respective language.
 
 ### :sparkles: Website champions
+
 Website champions are those who focus on the website (this includes playground). Maybe you are a designer or coder that loves to create great interactions for user, then this is would be for you!
 
 ## Becoming a champion
+
 There can be many ways to become a champion, but what they all have in common is regularly contributing to the project. There is no limit to who or how many can become champions of a specific area and you can also become champion of multiple areas.
 
 ### How to get started
+
 The first step is always to get to know the tool, explore how and what it does. If you like to make your own side projects, try using Modelina and as you find issues, raise them and maybe even solve them. You can also look for [good first issues](https://github.com/asyncapi/modelina/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22), that are well described issues tailored for new contributors.
 
-As you become more and more familiar with the project and continue to contribute, naturally you become a champion, like two rivers merging. 
+As you become more and more familiar with the project and continue to contribute, naturally you become a champion, like two rivers merging.
 
 # Champion Guidelines
 
 The guidelines are highly inspired by [the Brew Maintainer Guidelines](https://docs.brew.sh/Maintainer-Guidelines).
 
-This section are meant to serve as guiding principles for champions and what the privilege entitles. Remember, as a team we **Prioritise Champions Over Users** to avoid burnout. 
+This section are meant to serve as guiding principles for champions and what the privilege entitles. Remember, as a team we **Prioritise Champions Over Users** to avoid burnout.
 
 If you wish to change or discuss any of the champion guidelines: open a PR to suggest a change, or create an issue detailing the change you wish to see.
 
 ## Reviewing a PR
+
 To ensure a certain level of quality all champions must make sure the following is uphold before accepting a PR:
 
 1. All **required** CI checks MUST pass. Unless a specific reason is given it should not.
@@ -58,6 +67,7 @@ To ensure a certain level of quality all champions must make sure the following
 5. Make sure that [Versioning and maintenance](#Versioning-and-maintenance) is uphold.
 
 ### Merging a PR
+
 There are a few ways to merge a PR, depending on whether your are a champion or contributor.
 
 Any champion can merge any PR they have carefully reviewed and is passing CI that has been opened by another champion. If you do not wish to have other champions merge your PRs: please use the do not merge label (or the command `/dnm`) to indicate that you will personally merge it when it's ready.
@@ -67,17 +77,20 @@ One of the issues for champions is that it normally require a review from anothe
 Therefore we enforce **Lazy consensus** when it comes to features and changes to the project.
 
 #### Merging without review
+
 Merging without having another champion review your code, require a special set of requirements to be met before allowed to do so. They are as follows:
 
 - Must do a self review following [Reviewing a PR](#Reviewing-a-PR).
-- Must give other champions adequite time to check your code, at least 5 days (120 hours after review was requested). Exceptions: this do not apply for PR that changes documentation, the website, examples, CI, or tests. 
+- Must give other champions adequite time to check your code, at least 5 days (120 hours after review was requested). Exceptions: this do not apply for PR that changes documentation, the website, examples, CI, or tests.
 
 If a champion is on holiday/vacation/sick during this time and leaves comments after they are back: please treat post-merge PR comments and feedback as you would if left within the time period and follow-up with another PR to address their requests (if agreed).
 
 ## Versioning and maintenance
-As of version 1, Modelina has a very strict set of changes we are allowed to do before it requires a major version change. In short, any changes that change the generated outcome are not allowed as it's a breaking change for the consumer of the generated models. 
+
+As of version 1, Modelina has a very strict set of changes we are allowed to do before it requires a major version change. In short, any changes that change the generated outcome are not allowed as it's a breaking change for the consumer of the generated models.
 
 Here is a list of changes we are allowed to do that would not require a breaking change:
+
 - Adding new features (that do not change existing output), such as generators, presets, input processors, etc.
 - Change existing features, by providing options that default to current behavior. This could be a preset that adapts the output based on options, as long as the API of Modelina and the API of the generated models does not have any breaking changes.
 - Bug fixes where the generated code is otherwise unusable (syntax errors, etc).
@@ -93,11 +106,12 @@ Major versions are currently happening at a 3-month cadence (in a similar fashio
 ## Communication
 
 Maintainers have a variety of ways to communicate with each other:
+
 - Modelina's repository on GitHub
 - Private communications between one or more champions on private channels (e.g. Slack)
 - AsyncAPI Slack tooling channel
 
-All communication should ideally occur in public on GitHub or the AsyncAPI Slack tooling channel. Where this is not possible or appropriate (e.g. a security disclosure, interpersonal issue between champions, urgent breakage that needs to be resolved) this can move to champions’ private group communication and, if necessary, 1:1 communication. 
+All communication should ideally occur in public on GitHub or the AsyncAPI Slack tooling channel. Where this is not possible or appropriate (e.g. a security disclosure, interpersonal issue between champions, urgent breakage that needs to be resolved) this can move to champions’ private group communication and, if necessary, 1:1 communication.
 
 Technical decisions should not happen in 1:1 communications but if they do (or did in the past) they must end up back as something linkable on GitHub. For example, if a technical decision was made a year ago on Slack and another champions/contributor/user asks about it on GitHub, that’s a good chance to explain it to them and have something that can be linked to in the future.
 
@@ -108,6 +122,7 @@ All champion communication through any medium is bound by Modelinas Code of Cond
 Maintainers should feel free to pleasantly disagree with the work and decisions of other champions. Healthy, friendly, technical disagreement between champions is actively encouraged and should occur in public on the issue tracker to make the project better. Interpersonal issues should be handled privately in Slack, ideally with moderation. If work or decisions are insufficiently documented or explained any champion or contributor should feel free to ask for clarification. No champion may ever justify a decision with e.g. “because I say so” or “it was I who did X” alone. Off-topic discussions on the issue tracker, bike-shedding and personal attacks are forbidden.
 
 ## Stepping down as a champion
+
 There can be countless reasons why you want to step down as a champion and it is entirely your provocative at any time.
 
 To step down as a champion make a PR removing your name from the [CODEOWNERS file](../CODEOWNERS) and thats it :v:
diff --git a/docs/constraints.md → docs/constraints/README.md b/docs/constraints.md → docs/constraints/README.md
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -23,10 +23,10 @@ The Acceptance Criteria for _adding new features_ requires a few things in order
 1. **Not all feature requests from the community (or maintainers!) are accepted:** Even though you are welcome to create a new feature without an issue, it might be rejected and turn out to be a waste of your time. We don't want that to happen, so make sure to create an issue first and wait to see if it's accepted after community discussion of the proposal.
 1. **When creating tests for your new feature, aim for as high coverage numbers as possible:** When you run the tests (`npm run test`), you should see a `./coverage/lcov-report/index.html` file being generated. Use this to see in depth where your tests are not covering your implementation.
 1. **No documentation, no feature:** If a user cannot understand a new feature, that feature basically doesn't exist! Remember to make sure that any and all relevant [documentation](./) is consistently updated.
-    - New features such as new presets, generators or inputs, etc, need associated use case documentation along side [examples](../examples). This is not only to showcase the feature, but to ensure it will always work. Checkout our [adding examples](#-adding-examples) doc for more information on how to do this.
+    - New features such as new presets, generators or inputs, etc, need associated use case documentation along side [examples](../examples). This is not only to showcase the feature, but to ensure it will always work. Checkout our [adding examples](#adding-examples) doc for more information on how to do this.
 
 ### Adding examples
-The Acceptance Criteria Process for _adding examples_ is not only something we use to showcase features, but also to ensure those features always work. _(This is important since it is picked up by [our CI system](#What-does–the-CI-system-do-when-I-create-a-PR).)_
+The Acceptance Criteria Process for _adding examples_ is not only something we use to showcase features, but also to ensure those features always work. _(This is important since it is picked up by [our CI system](#what-does–the-ci-system-do-when-i-create-a-pr).)_
 
 Adding examples is quite straight forward, so don't feel shy! Here's how to do it:
 1. Duplicate the [TEMPLATE folder](https://github.com/asyncapi/modelina/tree/master/examples/TEMPLATE) and rename it to something that makes sense for your feature. If you can't think of anything, feel free to go with your first thought, since we can always discuss it in the PR afterwards.

diff --git a/docs/inputs/JSON_Schema.md b/docs/inputs/JSON_Schema.md
@@ -136,16 +136,16 @@ The order of interpretation:
 - `true` boolean schema infers all model types (`object`, `string`, `number`, `array`, `boolean`, `null`, `integer`) schemas.
 - `type` infers the initial model type.
 - `required` are interpreted as is.
-- `patternProperties` are merged together with any additionalProperties, where duplicate pattern models are [merged](#Merging-models).
-- `additionalProperties` are interpreted as is, where duplicate additionalProperties for the model are [merged](#Merging-models). If the schema does not define `additionalProperties` it defaults to `true` schema.
-- `additionalItems` are interpreted as is, where duplicate additionalItems for the model are [merged](#Merging-models). If the schema does not define `additionalItems` it defaults to `true` schema.
-- `items` are interpreted as ether tuples or simple array, where more than 1 item are [merged](#Merging-models). Usage of `items` infers `array` model type.
-- `properties` are interpreted as is, where duplicate `properties` for the model are [merged](#Merging-models). Usage of `properties` infers `object` model type.
+- `patternProperties` are merged together with any additionalProperties, where duplicate pattern models are [merged](#merging-models).
+- `additionalProperties` are interpreted as is, where duplicate additionalProperties for the model are [merged](#merging-models). If the schema does not define `additionalProperties` it defaults to `true` schema.
+- `additionalItems` are interpreted as is, where duplicate additionalItems for the model are [merged](#merging-models). If the schema does not define `additionalItems` it defaults to `true` schema.
+- `items` are interpreted as ether tuples or simple array, where more than 1 item are [merged](#merging-models). Usage of `items` infers `array` model type.
+- `properties` are interpreted as is, where duplicate `properties` for the model are [merged](#merging-models). Usage of `properties` infers `object` model type.
 - [allOf](#allOf-sub-schemas)
-- `dependencies` only apply to schema dependencies, since property dependencies adds nothing to the underlying model. Any schema dependencies are interpreted and then [merged](#Merging-models) together with the current interpreted model.
+- `dependencies` only apply to schema dependencies, since property dependencies adds nothing to the underlying model. Any schema dependencies are interpreted and then [merged](#merging-models) together with the current interpreted model.
 - `enum` is interpreted as is, where each `enum`. Usage of `enum` infers the enumerator value type to the model, but only if the schema does not have `type` specified.
 - `const` interpretation overwrite already interpreted `enum`. Usage of `const` infers the constant value type to the model, but only if the schema does not have `type` specified.
-- [allOf/oneOf/anyOf/then/else](#Processing-sub-schemas)
+- [allOf/oneOf/anyOf/then/else](#processing-sub-schemas)
 - [not](#interpreting-not-schemas)
 
 ## Interpreting not schemas
@@ -160,7 +160,7 @@ Currently, the following `not` model properties are interpreted:
 - boolean `not` schemas are not applied.
 
 ## Processing sub schemas
-The following JSON Schema keywords are [merged](#Merging-models) with the already interpreted model:
+The following JSON Schema keywords are [merged](#merging-models) with the already interpreted model:
 - `allOf`
 - `oneOf`
 - `anyOf`
@@ -170,7 +170,7 @@ The following JSON Schema keywords are [merged](#Merging-models) with the alread
 ## Merging models
 Because of the recursive nature of the interpreter (and the nested nature of JSON Schema) it happens that two models needs to be merged together. 
 
-If only one side has a property defined, it is used as is, if both have it defined they are merged based on the following logic (look [here](./input_processing.md#Internal-model-representation) for more information about the CommonModel and its properties):
+If only one side has a property defined, it is used as is, if both have it defined they are merged based on the following logic (look [here](./input_processing.md#internal-model-representation) for more information about the CommonModel and its properties):
 - `additionalProperties` if both models contain it the two are recursively merged together. 
 - `patternProperties` if both models contain it each pattern model are recursively merged together. 
 - `properties` if both models contain the same property the corresponding models are recursively merged together. 

diff --git a/docs/internal-model.md b/docs/internal-model.md
@@ -33,7 +33,7 @@ This means that if you accessed `EnumValueModel.key` you would get `something% s
 
 How and what are constrained?
 
-The answer to this question is not straightforward, cause each output has unique constraints that the meta models must adhere to. You can read more about [the constraint behavior here](constraints.md).
+The answer to this question is not straightforward, cause each output has unique constraints that the meta models must adhere to. You can read more about [the constraint behavior here](./constraints.md).
 
 <p align="center">
   <img src="./img/ConstrainedMetaModel.png" />

diff --git a/docs/migration.md → docs/migrations/README.md b/docs/migration.md → docs/migrations/README.md
@@ -1,7 +1,7 @@
 # Migration guides
 
-As Modelina progresses and evolves over time, sometimes it's inevitable that a major version change is required.
+As Modelina progresses and evolves, sometimes it's inevitable that a major version change is required.
 
 When it happens, we try to list the breaking changes and a migration guide, to make transitioning from one major version to another as painless as possible.
 
-- [From v0 to v1](./migrations/version-0-to-1.md)
+- [From v0 to v1](./version-0-to-1.md)