docarray · samsja · Apr 18, 2023 · Apr 18, 2023 · Apr 18, 2023 · Apr 18, 2023
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -49,7 +49,7 @@ There are also a couple of nice to haves:
 
 **Note:** If you're just fixing a typo or grammatical issue, you can go straight to a pull request.
 
-### Associate with GitHub account
+### Associate with your GitHub account
 
 - Confirm username and email on [your profile page](https://github.com/settings/profile).
 - Set git config on your computer.
@@ -68,8 +68,7 @@ git log  # to confirm the change is effective
 git push --force
 ```
 
-### Installing dependencies using 
-
+### Installing dependencies using Poetry
 
 We use [Poetry](https://python-poetry.org/) to manage our dependencies.
 
@@ -83,6 +82,7 @@ poetry install --all-extras # this will install all of the dependency needed for
 This will automatically create a virtual environment and install all the dependency from the `lockfile` of Poetry.
 
 To run your code you need to either activate the environment:
+
 ```shell
 poetry shell
 python XYZ
@@ -163,18 +163,18 @@ feat: add hat wobble
 +-------> Type: build, ci, chore, docs, feat, fix, refactor, style, or test.
 ```
 
-- ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
-- docs: Documentation only changes
-- feat: A new feature
-- fix: A bug fix
-- perf: A code change that improves performance
-- refactor: A code change that neither fixes a bug nor adds a feature
-- test: Adding missing tests or correcting existing tests
-- chore: updating grunt tasks etc.; no production code change
+- `ci`: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
+- `docs`: Documentation only changes
+- `feat`: A new feature
+- `fix`: A bug fix
+- `perf`: A code change that improves performance
+- `refactor`: A code change that neither fixes a bug nor adds a feature
+- `test`: Adding missing tests or correcting existing tests
+- `chore`: updating grunt tasks etc.; no production code change
 
 ### Writing your commit message
 
-A good commit message helps us track DocArray's development. A Pull Request with a bad commit message will be *rejected* automatically in the CI pipeline.
+A good commit message helps us track DocArray's development. A pull request with a bad commit message will be *rejected* automatically in the CI pipeline.
 
 Commit messages should stick to our [naming conventions](#-naming-conventions) outlined above, and use the format `type(scope?): subject`:
 
@@ -239,16 +239,19 @@ If appropriate, make the dependency optional. For example if it is a new library
 
 `mylib = {version = ">=X.y.z", optional = true }`
 
-you will also need to add an extra:
+You will also need to add an extra:
+
 ```toml
 [tool.poetry.extras]
 new_modalities = ['mylib']
 ```
 
 Note: Manual editing of `pyproject.toml` is equivalent  to `poetry add "mylib>=3.9"  -E new_modalities`
+
 <a name="-testing-docarray-locally-and-on-ci"></a>
 ## 💥 Testing DocArray Locally and on CI
-Locally you can run the test via:
+
+Locally you can run the tests via:
 
 ```bash
 poetry install --all-extras
@@ -257,22 +260,27 @@ poetry run pip install tensorflow
 poetry run pytest -v -s tests
 ```
 
-for local development we suggest to use the following command to run the tests
+For local development we suggest using the following command to run the tests:
+
 ```bash
 poetry run pytest -v -s tests -m 'not tensorflow and not slow and not internet'
 ```
-This only take a couple of second.
+
+This only take a couple of seconds.
 
 ### Test policy
 
 Every contribution that adds or modifies the behavior of a feature must include a suite of tests that validates that the feature works as expected.
 
 This allows:
+
 * the reviewer to be very confident that the feature does what it is supposed to do before merging it into the code base.
 * the contributors to be sure that they don't break already-merged features when refactoring or modifying the code base.
 
 <a name="-enable-logging"></a>
 ## Enable logging
+
+
 If you need to monitor and debug your code, you can enable docarray logging:
 ```python
 import logging
@@ -292,14 +300,17 @@ If you _do_ make modification in a `.proto` file, you need to **recompile the pr
 In order to maintain compatibility with most of the Python ecosystem, in DocArray we compile to two different protobuf
 versions. Therefore, compilation is a two-step process:
 
-1. **Step 1:** Compile using `protoc` version 3.19
-   1. Download protoc v3.19 as appropriate for your system, e.g. from [here](https://github.com/protocolbuffers/protobuf/releases/tag/v3.19.5)
-   2. Unzip the file and make `protoc` executable: `chmod +x bin/protoc`
-   3. Compile the protobuf definitions in the `pb2` directory. From `docarray/proto/` run `path/to/v-3-19/bin/protoc -I . --python_out="pb2" docarray.proto`.
-2. **Step 2:** Compile using `protoc` version 3.21
-    1. Download protoc v3.21 as appropriate for your system, e.g. from [here](https://github.com/protocolbuffers/protobuf/releases/tag/v21.12)
-    2. Same as above
-    3. Compile the protobuf definitions in the `pb` directory. From `docarray/proto/` run `path/to/v-3-21/bin/protoc -I . --python_out="pb" docarray.proto`.
+### Step 1: Compile using `protoc` version 3.19
+
+1. Download protoc v3.19 as appropriate for your system, e.g. from [here](https://github.com/protocolbuffers/protobuf/releases/tag/v3.19.5)
+2. Unzip the file and make `protoc` executable: `chmod +x bin/protoc`
+3. Compile the protobuf definitions in the `pb2` directory. From `docarray/proto/` run `path/to/v-3-19/bin/protoc -I . --python_out="pb2" docarray.proto`.
+
+### Step 2: Compile using `protoc` version 3.21
+
+1. Download protoc v3.21 as appropriate for your system, e.g. from [here](https://github.com/protocolbuffers/protobuf/releases/tag/v21.12)
+2. Same as above
+3. Compile the protobuf definitions in the `pb` directory. From `docarray/proto/` run `path/to/v-3-21/bin/protoc -I . --python_out="pb" docarray.proto`.
 
 <a name="-contributing-documentation"></a>
 ## 📖 Contributing documentation
@@ -321,17 +332,8 @@ Good docs make developers happy, and we love happy developers! We've got a few d
 7. Think about the **structure** of the page beforehand. Split it into headers before writing the content.
 8. If relevant, include a “**See also**” section at the end.
 9. Link to any existing explanations of the concepts you are using.
-
-Bonus: **Know when to break the rules**. Documentation writing is as much art as it is science. Sometimes you will have to deviate from these rules in order to write good documentation.
-
-[MyST](https://myst-parser.readthedocs.io/en/latest/) Elements Usage
-
-1. Use the `{tab}` element to show multiple ways of doing one thing. [Example](https://docarray.jina.ai/fundamentals/document/#document) 
-2. Use the `{admonition}` boxes with care.
-3. Use `{dropdown}` to hide optional content, such as long code snippets or console output.
-
-
-Note: Example code in the documentation should also follow our [code style conventions]().
+10. Example code in the documentation should also follow our code style.
+11. **Know when to break the rules**. Documentation writing is as much art as it is science. Sometimes you will have to deviate from these rules in order to write good documentation.
 
 ### Building documentation on your local machine
 
@@ -346,19 +348,19 @@ Note: Example code in the documentation should also follow our [code style conve
 cd docs
 pip install -r requirements.txt
 export NUM_RELEASES=10
-bash makedoc.sh local-only
+bash makedoc.sh
 ```
 
-Docs website will be generated in `_build/dirhtml`
-To serve it, run
+The docs website will be generated in `site`.
+To serve it, run:
 
 ```bash
-cd _build/dirhtml
+mkdocs serve
 python -m http.server
 ```
 
 You can now see docs website on [http://localhost:8000](http://localhost:8000) on your browser.
 
-## 🙏 Thank You
+## 🙏 Thank you
 
 Once again, thanks so much for your interest in contributing to DocArray. We're excited to see your contributions!