created contributing.md #120
Conversation
|
Hi @ocefpaf, I couldn't able to understand why this pre-commit check gets failed, can you clear this out? |
If you click on the link it will list all the failures. They ar mostly related to long lines and we can fix them in another PR. The file you added seems to be OK. |
|
So, is the documentation written is fine enough? |
CONTRIBUTING.md
Outdated
| @@ -0,0 +1,249 @@ | |||
| # Contributors Guide | |||
|
|
|||
| Interested in helping out the IOOS QARTOD? | |||
There was a problem hiding this comment.
QARTOD is 1 module of ioos_qc. There are others QA/QC standards implemented here.
| Interested in helping out the IOOS QARTOD? | |
| Interested in helping out the ioos_qc? |
CONTRIBUTING.md
Outdated
|
|
||
| ## Introduction | ||
|
|
||
| First off, thank you for considering contributing to IOOS QARTOD! |
There was a problem hiding this comment.
| First off, thank you for considering contributing to IOOS QARTOD! | |
| First off, thank you for considering contributing to ioos_qc! |
CONTRIBUTING.md
Outdated
|
|
||
| First off, thank you for considering contributing to IOOS QARTOD! | ||
|
|
||
| QARTOD is collection of utilities, scripts and tests to assist in automated quality assurance and quality control for oceanographic datasets and observing systems. |
There was a problem hiding this comment.
Please replace all QARTOD references to the name to the library ioos_qc.
CONTRIBUTING.md
Outdated
| This can also be installed from a variety of package managers, including ``conda`` if needed. | ||
|
|
||
| Login to your [GitHub](https://github.com) account and make a fork of the | ||
| [IOOS_QC repository](https://github.com/ioos/ioos_qc) by clicking the "Fork" button. |
There was a problem hiding this comment.
It is odd but the library name should be lower case.
| [IOOS_QC repository](https://github.com/ioos/ioos_qc) by clicking the "Fork" button. | |
| [ioos_qc repository](https://github.com/ioos/ioos_qc) by clicking the "Fork" button. |
CONTRIBUTING.md
Outdated
|
|
||
| For Environment Setup: | ||
|
|
||
| After ``-n`` you can specify any name you'd like; here we've chosen ``ioosqc38``. |
There was a problem hiding this comment.
| After ``-n`` you can specify any name you'd like; here we've chosen ``ioosqc38``. | |
| After ``-n`` you can specify any name you'd like; here we've chosen ``ioosqc312`. |
There was a problem hiding this comment.
But in the documentation its, written the ioosqc38, so I guess we need to fix that as well.
There was a problem hiding this comment.
The contributing guide will replace any contributing instructions in the docs. We will remove those later in another PR. That is why I requested you to try to build it in a comment below.
CONTRIBUTING.md
Outdated
| **IMPORTANT**: Always activate this environment when developing and testing your changes! | ||
|
|
||
| ```sh | ||
| conda activate ioosqc38 |
There was a problem hiding this comment.
| conda activate ioosqc38 | |
| conda activate ioosqc312 |
CONTRIBUTING.md
Outdated
| Finally, to run all the tests! | ||
|
|
||
| ```sh | ||
| pytest |
There was a problem hiding this comment.
Please check the line we have in the GitHub Actions file and use it here. We have some extra options.
CONTRIBUTING.md
Outdated
| Create the following environment: | ||
|
|
||
| ```sh | ||
| conda create -y -n ioosqc38_docs python=3.8 |
There was a problem hiding this comment.
Please change all references of Python 3.8 to Python 3.12
CONTRIBUTING.md
Outdated
| Currently there are no packages in this environment, let's change that. | ||
|
|
||
| ```sh | ||
| conda install -y --file requirements.txt \ --file requirements-dev.txt \ --file docs/requirements.txt |
There was a problem hiding this comment.
We should simplify this later but it is OK for now. We don't need so many requirements file. We should probably add those to pyproject.toml.
| conda install -y --file requirements.txt \ --file requirements-dev.txt \ --file docs/requirements.txt | |
| conda install --file requirements.txt --file requirements-dev.txt --file docs/requirements.txt |
| make html | ||
| ``` | ||
| Then open a browser to: | ||
| ``build/html/index.html`` |
There was a problem hiding this comment.
Did you try building our docs? Are you familiar with sphinx? That could be a nice exercise to understand a bit more of our infrastructure.
There was a problem hiding this comment.
Yes, I tried building the docs. And no, I am not familiar with sphinx.
There was a problem hiding this comment.
Did you succeed? If not what were to problems you faced that could be added as instructions here?
There was a problem hiding this comment.
Yes, I got succeeded, do received some warnings, but it build successfully.
There was a problem hiding this comment.
Interesting. Do you want to tackle those warnings? Any missing packages that you had to install that were not in the requirement.txt file?
There was a problem hiding this comment.
No packages needed. And it will build automatically, nothing to tackle with.
There was a problem hiding this comment.
Interesting. I had to install pooch, which is not specified in any of our requirement files, and adapt an old notebook with a new syntax for erddapy. I wonder if your build ran the notebooks correctly then, you should've seen these failures.
Anyways, let's tackle the build warnings in a next PRs.
There was a problem hiding this comment.
Oh my bad!
I just tried to run one of the notebooks tests, and there it shows those module errors. Sorry for that, I thought once the build is done, everything is fine.
So, I will add those missing modules in the requirements files. Will open the PR for its same.
So sorry for that once again.
Fix Issue #103