mariangela/docs-mi

This repository contains the source code for WSO2 Micro Integrator documentation.

WSO2 Micro Integrator Documentation

This repository contains the source code for WSO2 Micro Integrator documentation. Please note that this documentation is a work in progress.

This repository is open and we welcome your contributions!

To access the WSO2 Micro Integrator documentation site, visit https://mi.docs.wso2.com/.

Follow the below topics to learn more:

• Contributing to WSO2 Micro Integrator documentation
  • For minor modifications
  • For major modifications
• Running the project locally
• Signing the CLA

Contributing to WSO2 Micro Integrator documentation

As an open-source project, WSO2 Micro Integrator documentation welcomes contributions from the community. Before you contribute, read the following guidelines to understand how you can contribute:

For minor modifications

Follow the steps below if you need to perform a minor modification (For example: changing a term, fixing a link, adding another bullet point, etc.):

1. Go to the page you want to edit.
2. Click the edit (pen) icon in the top right corner.
3. Edit the .md file.
4. Add a commit message and commit. This will open a Pull Request (PR).
5. Fill in the relevant details and submit the PR.
6. Get the PR reviewed and merged by a maintainer.

For major modifications

Follow the steps below if you need to perform a major modification (For example: adding a new page, replacing an image, etc.):

Prerequisites:

Set up the machine and run the project locally by following the Running the project locally documentation.

1. When working, always start by getting a pull from upstream so that you are in sync with the upstream.

2. In your forked repository, make your changes in a new git branch.

3. The docs-mi/en/docs/ directory contains all the .md files with content. Find the relevant location and do the modification.

   NOTE:

   Refer to the Markdown Cheat Sheet for styling and formatting.

4. Navigate to the docs-mi/en/ directory in the terminal and build the repository with the following command:

   mkdocs serve

   NOTE:

   Refer to Run MkDocs for more information.

5. If the styling and formatting are fine, you can commit the changes, push them and send in a pull request.

Running the project locally

To locally execute the project, ensure that both Python and pip are installed on your machine.

Step 1 - Install Python

MacOS

1. If you are using MacOS, it is likely that a version of Python is pre-installed on your machine. To confirm this, execute the following command in your terminal:

   python --version

   Upon running the command, you should observe an output similar to the following example which is the default version of Python on your machine:

   Python 2.7.2

2. You also need to install python3. Check if you have python3 installed by running the following command:

   python3 --version

   NOTE:

   For a seamless experience and compatibility with the versions of MkDocs and other plugins we utilize, it is recommended to use Python 3.8.x, 3.9.x, or 3.10.x.

3. If you don't have Python installed, download Python from the official downloads page and install.

4. Verify the python3 version by running the following command:

   python3 --version

   Upon running the command, you should observe an output similar to the following:

   Python 3.9.6

• Once you are done, you will have two versions of Python on your machine; python2 and python3.

Ubuntu and other versions of Debian Linux

• python3 is pre-installed in these versions, which you can verify with python3 -V.

• Run sudo apt install -y python3-pip to install pip and verify with pip3 -V.

Step 2 - Install Pip

pip is already installed if you are using Python 3 >=3.4 downloaded from python.org.

• Verify the pip3 version by running the following command:

  pip3 --version

  Upon running the command, you should observe an output similar to the following:

  pip 21.2.4

• If pip is not already installed on your machine, download get-pip.py to install pip by clicking here. Then run the following command to install it:

  python3 get-pip.py

Step 3 - Fork the repository

Fork the GitHub repository: https://github.com/wso2/docs-mi.git

Step 4 - Clone the repository

Navigate to the location where you want to clone the repository and clone the forked repository.

git clone https://github.com/<git-username>/docs-mi.git

Step 5 - Install the dependencies

1. Navigate to the <language-folder> inside the folder containing the repository that you cloned.

   cd docs-mi/en/

2. Install the required pip packages.

   This will install MkDocs and the required theme, extensions, and plugins.

   For python3, use the following command:

   pip3 install -r requirements.txt

Step 5 - Run MkDocs

1. Run the following command to start the server and view the site on your local server.

   mkdocs serve

   NOTE:

   If you get any error saying that MkDocs command is not found, try the following command:

   python3 -m mkdocs serve
   

2. Open the following URL on a new browser window to view the Micro Integrator documentation site locally:

   http://localhost:8000

   INFO:

   If you are making changes and want to see them on the fly, run the following command to start the server and view the site on your local server.

   1. Navigate to the mkdocs.yml file.

   2. Change the following configuration to false as shown below:

      #Breaks build if there's a warning
      strict: false
      

   3. Run the following command to start the server and to make the server load only the changed items and display the changes faster.

      mkdocs serve --dirtyreload

   4. If you are running the mkdocs serve --dirtyreload command to run the MkDocs server, make sure to change the configuration in the mkdocs.yml file as follows before sending a pull request.

      strict: true

Signing the CLA

• Accept and sign the Contributor License Agreement (CLA) before sending pull requests. For any changes to be accepted, the CLA must be signed.

• You need to accept the CLA when you are prompted via a GitHub email notification on sending your first PR. Subsequent PRs will not require CLA acceptance.

• If the CLA gets changed for some (unlikely) reason, you will be presented with the new CLA text after sending your first PR after the change.

License

Licenses this source under the Apache License, Version 2.0 (LICENSE). You may not use this file except in compliance with the License.