Home
A brief description of our Documentation Website https://eclipse-tractusx.github.io/
Our documentation website was developed with Docusaurus 2.0 for the simplicity and benefits it offers for maintenance, upgrades, and contributions that can be performed in a simple and intuitive manner.
As an allowed user, you'll encounter 2 possible scenarios to modify the documentation of the project. In the following, you'll find instructions on how to modify the documentation in either scenario:
One of the benefits of Docusaurus 2.0 is that if you create a doc by adding an .md &/or .mdx file under the mentioned folders (each folder is dedicated to an specific content which will be be explained in detail), a page will automatically be generated according to our theme. For more information about configuration, styling and advanced topics, please consult the documentation.
Tip If you don't want to display the content of an .md file as a page, and avoid that its content is generated as a sidebar item, (sidebar) you should prefix the name of the file with an underscore key (_). In that way Docusaurus will ignore this file and will not generate a Docs page for its content.
Example: _example.md
In the Plugins section, we describe the plugins involved in the .yaml files retrieval process that define the endpoints and methods of the various applications documented on our site. We also describe the generation of documents in the form of pages that present the .yaml content in a clear and interactive way.
In the development of this project, we have used MaterialUI for the creation of the components detailed below:
The <FAQsComponent /> and <ProductAccordionCard /> make use of a Basic Accordion, to toggle the answers to the frequently asked questions that we receive about the use of this application and the list of Products displayed in the community page.
The components forming the mentioned UI are imported as follows:
import Accordion from '@mui/material/Accordion';
import AccordionSummary from '@mui/material/AccordionSummary';
import AccordionDetails from '@mui/material/AccordionDetails';
import Typography from '@mui/material/Typography';
import ExpandMoreIcon from '@mui/icons-material/ExpandMore';
Our <NewsTickerComponent /> is developed with the help of React-slick:"^0.29.0" and its Slick-Carousel:"^1.8.1".
For its installation and use, you can follow one of these links:
In our project, we use the NewsTicker component to display the main titles of news written in the ./blog folder and displayed in the HomePageHeader component.
-
Docusaurus-Plugin-Remote-Content GitHub Repo
With this plugin, we are able to retrieve files containing the yaml definitions of the methods and endpoints we are interested in from any site/repository (GitHub or not). Once the file is fetched, a local copy is generated. We can then manipulate the copy and store it as we see fit.
Its configuration and use is described here
Note In our project, we use npm as our package manager. The documentation of the plugin uses yarn. Make sure you change the command line by adapting the declaration, for example: npm install docusaurus-plugin-remote-content instead of yarn add docusaurus-plugin-remote-content
For example, if we want to retrieve and have a local copy of example.yaml located at https://my-page.com/folder1/subfolder1.1/example.yaml we should add the next declaration in the plugins object of our local docusaurus.config.js:
module.exports = {
// ...
plugins: [
[
"docusaurus-plugin-remote-content",
{
// options here
name: "my-example", // used by CLI, must be path safe
sourceBaseUrl: "https://my-page.com/folder1/subfolder1.1/", // the base url for the markdown (gets prepended to all of the documents when fetching)
outDir: "openApi/example", // the base directory to output to.
documents: ["example.yaml"], // the file names to download, if other file share the `sourceBaseUrl`, you can add it here without the need of create another instance of the plugin
},
],
[
// ...another instance of the plugin
]
],
}Important: if the sourceBaseUrl from where you retrieve data is not a live page, you must provide the raw link as a source.
For more information regarding the options of this plugin, check here
-
Docusaurus-OpenApi-Docs GitHub Repo
Once we have the yaml file with the definitions of the methods, either obtained via the Docusaurus-Plugin-Remote-Content or because the file was defined locally in our project, we can generate documentation pages. To do this, we can take advantage of the Docusaurus features and the Docusaurus-OpenApi-Docs plugin. It generates .mdx files located in the docs-kits folder, which will be parsed into our predefined UI. Checkout our wiki page: Creating an open API Documentation for more specifics.
For example, out of the following yaml definition:
/api/catena/sites/{bpn}:
get:
tags:
- site-controller
summary: Get site partners by bpn
description: Get business partners of type site by bpn-s ignoring case.
operationId: getSite
parameters:
- name: bpn
in: path
description: Bpn value
required: true
schema:
type: string
responses:
'200':
description: Found site with specified bpn
content:
'*/*':
schema:
$ref: '#/components/schemas/SitePartnerSearchResponse'
'400':
description: On malformed request parameters
'404':
description: No site found under specified bpnThe following UI is generated:
Its use is quite straight forward and well documented. Please check the documentation. Here, we highlight some main things to consider:
- configuration of docusaurus.config for adding more instances
- plugin options to generate docs
- generate docs
- cleaning docs
Note In our project, we use npm as our package manager. The documentation of the plugin uses yarn. Make sure you change the command line by adapting the declaration, for example: npm install docusaurus-plugin-remote-content instead of yarn add docusaurus-plugin-remote-content