From 73bf6f0b03d98824452095ef4f50bf83a34f2a25 Mon Sep 17 00:00:00 2001 From: Alex C-G Date: Tue, 18 Apr 2023 13:20:54 +0200 Subject: [PATCH 1/5] docs(contributing): basic fixes Signed-off-by: Alex C-G --- CONTRIBUTING.md | 46 +++++++++++++++++++++++++++------------------- 1 file changed, 27 insertions(+), 19 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 332daa90ca4..a7a1bd3bce7 100644 --- 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` + ## 💥 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. ## Enable logging + + If you need to monitor and debug your code, you can enable docarray logging: ```python import logging @@ -324,7 +332,7 @@ Good docs make developers happy, and we love happy developers! We've got a few d 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 +#### [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. @@ -349,8 +357,8 @@ export NUM_RELEASES=10 bash makedoc.sh local-only ``` -Docs website will be generated in `_build/dirhtml` -To serve it, run +The docs website will be generated in `_build/dirhtml`. +To serve it, run: ```bash cd _build/dirhtml From ac8635b3f4b90b9e85c7c01c78c869f456c4e84b Mon Sep 17 00:00:00 2001 From: Alex C-G Date: Tue, 18 Apr 2023 13:22:34 +0200 Subject: [PATCH 2/5] docs(contributing): fix multi-level numbers list Signed-off-by: Alex C-G --- CONTRIBUTING.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a7a1bd3bce7..1bd1e17d121 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -300,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`. ## 📖 Contributing documentation From 787e1d8d2b6ab3ee0e67eaad8bcf67f12b7593b8 Mon Sep 17 00:00:00 2001 From: Alex C-G Date: Tue, 18 Apr 2023 13:22:55 +0200 Subject: [PATCH 3/5] docs(contributing): capitalization Signed-off-by: Alex C-G --- CONTRIBUTING.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1bd1e17d121..46a6938129b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -341,7 +341,6 @@ Bonus: **Know when to break the rules**. Documentation writing is as much art as 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](). ### Building documentation on your local machine @@ -370,6 +369,6 @@ 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! From b23d6b12f702baaac7be6900f083efe54011064a Mon Sep 17 00:00:00 2001 From: Alex Cureton-Griffiths Date: Tue, 18 Apr 2023 13:45:23 +0200 Subject: [PATCH 4/5] chore: accept suggestions Co-authored-by: samsja <55492238+samsja@users.noreply.github.com> Signed-off-by: Alex Cureton-Griffiths --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 46a6938129b..92e6adae731 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -356,14 +356,14 @@ 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 ``` -The docs website will be generated in `_build/dirhtml`. +The docs website will be generated in `site`. To serve it, run: ```bash -cd _build/dirhtml +mkdocs serve python -m http.server ``` From 3bc0f437d5621a0febdc99c6704474575c311e07 Mon Sep 17 00:00:00 2001 From: Alex C-G Date: Tue, 18 Apr 2023 15:51:28 +0200 Subject: [PATCH 5/5] docs(contributing): remove myst, add list items Signed-off-by: Alex C-G --- CONTRIBUTING.md | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 92e6adae731..c0ae7d78cc6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -332,16 +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