Docs/project organization (#6)

* add overview to the project organization

* add more reference to the topics

* add pre-commit configuration

* commit fix by the pre-commit hook

* add more information to project_organization

* fix the links in the docs

.github/workflows/build.yml

@@ -22,4 +22,4 @@ jobs:
       uses: codecov/codecov-action@v4
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
-        slug: ihmeuw-msca/pypkg
+        slug: ihmeuw-msca/pypkg

.github/workflows/deploy.yml

@@ -56,4 +56,4 @@ jobs:
           path: './docs/pages'
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v4

.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.4.2
+  hooks:
+    - id: ruff
+      args: [ --fix ]
+    - id: ruff-format
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v4.6.0
+  hooks:
+    - id: trailing-whitespace
+    - id: end-of-file-fixer
+- repo: https://github.com/pre-commit/mirrors-mypy
+  rev: v1.10.0
+  hooks:
+    - id: mypy
+      files: ^src

.vscode/settings.json

@@ -7,4 +7,4 @@
         },
         "editor.rulers": [80],
     },
-}
+}

CODE_OF_CONDUCT.md

@@ -108,4 +108,4 @@ at [https://www.contributor-covenant.org/translations][translations].
 
 [FAQ]: https://www.contributor-covenant.org/faq
 
-[translations]: https://www.contributor-covenant.org/translations
+[translations]: https://www.contributor-covenant.org/translations

LICENSE

@@ -22,4 +22,4 @@ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -17,5 +17,5 @@ when building a Python package, include
 * Testing and documentation
 * Continuous integration and deployment
 
-It will bring standards, consistency and best practices into your projects and 
+It will bring standards, consistency and best practices into your projects and
 make collaborations easier.

docs/_static/css/custom.css

@@ -16,4 +16,4 @@ h6 {
   font-size: 1rem;
   font-weight: 500;
   margin: auto;
-}
+}

docs/_templates/sidebar/variant-selector.html

@@ -12,4 +12,4 @@
     </ul>
   <li>
   </ul>
-</div>
+</div>

docs/api_reference/index.rst

@@ -10,4 +10,4 @@ API reference
 .. note::
    Briefly describe the organization of the API reference if any.
 
-In PyPkg, we only provide a dummy function :py:func:`.example.add` to show the bone structure of a Python pacakge.
+In PyPkg, we only provide a dummy function :py:func:`.example.add` to show the bone structure of a Python pacakge.

docs/developer_guide/index.rst

@@ -8,4 +8,4 @@ Developer guide
 
     * briefly describe how to contribute
     * contributing to the documentation
-    * contributing to the code base
+    * contributing to the code base

docs/getting_started/index.rst

@@ -3,7 +3,7 @@ Getting started
 
 .. toctree::
    :hidden:
-   
+
    installation
    quickstart
 
@@ -22,4 +22,4 @@ It tries to show the basic bone structure of a package with minimal functionalit
 It is meant to be used as a starting point for new packages.
 
 For installing the package please check :ref:`Installing PyPkg`.
-For a simple example please check :ref:`Quickstart`.
+For a simple example please check :ref:`Quickstart`.

docs/getting_started/installation.rst

@@ -23,4 +23,4 @@ development mode.
 
     git clone https://github.com/ihmeuw-msca/pypkg.git
     cd pypkg
-    pip install -e ".[test,docs]"
+    pip install -e ".[test,docs]"

docs/index.rst

@@ -42,6 +42,6 @@ make collaborations easier.
 
    * - :ref:`API reference`
      - :ref:`Developer guide`
-   
+
    * - If you are looking for information on a specific module, function, class or method, this part of the documentation is for you.
      - Want to improve the existing functionalities and documentation? The contributing guidelines will guide you through the process.

docs/meta.toml

@@ -1,3 +1,3 @@
 versions = [
     "0.1.0",
-]
+]

docs/user_guide/cicd.rst

@@ -2,8 +2,8 @@ CI/CD
 =====
 
 .. admonition:: Working in progress...
-    :class: attention   
-    
+    :class: attention
+
     * introduce some basic concept of continuous integration and deployment
     * introduce github workflow
-    * introduce badges
+    * introduce badges

docs/user_guide/documentation.rst

@@ -5,4 +5,4 @@ Documentation
     :class: attention
 
     * introduce sphinx
-    * describe the multi-version documentation building process
+    * describe the multi-version documentation building process

docs/user_guide/index.rst

@@ -19,4 +19,4 @@ User guide
 
 This user guide introduces and explains some key concepts when building a Python package.
 If you are a new user starting out your Python package journey, we recommend you to start with the
-:ref:`Project organization` and read each section in order.
+:ref:`Project organization` and read each section in order.

docs/user_guide/project_organization.rst

@@ -4,4 +4,39 @@ Project organization
 .. admonition:: Working in progress...
     :class: Attention
 
-    Explain what different files and folders in the repo mean...
+    Explain what different files and folders in the repo mean...
+
+Here we describe what each file and folder in the project means and provide references and examples.
+
+* :code:`.github/workflows`: GitHub Actions workflows for continuous integration and deployment.
+    * For more please check :ref:`CI/CD`.
+* :code:`.vscode`: VSCode configurations.
+    * We use `Visual Studio Code <https://code.visualstudio.com>`_ as our main IDE.
+    * `Getting Started with Python in VS Code <https://code.visualstudio.com/docs/python/python-tutorial>`_.
+* :code:`.gitignore`: Files and folders that are ignored by Git.
+    * For formal documentation please check `here <https://git-scm.com/docs/gitignore>`_.
+    * For more please check `the list of common gitignore <https://github.com/github/gitignore>`_.
+    * We use the `gitignore extension <https://marketplace.visualstudio.com/items?itemName=codezombiech.gitignore>`_ in VSCode to conveniently genterate gitignore file.
+* :code:`src`: Source code of the project.
+    * For a minimum example of the source folder, please check `A simple project <https://packaging.python.org/en/latest/tutorials/packaging-projects/#a-simple-project>`_.
+* :code:`docs`: Documentation of the project.
+    * We use `Sphinx <https://www.sphinx-doc.org/en/master/>`_ to build documentation.
+    * For more please check :ref:`Documentation`.
+* :code:`tests`: Tests of the project.
+    * We use `Pytest <https://docs.pytest.org/en/stable/>`_ as the testing framework.
+    * For more please check :ref:`Testing`.
+* :code:`pyproject.toml`: Metadata of the project. This is enssential for Python packaging.
+    * For more information please check `this guide <https://packaging.python.org/en/latest/guides/writing-pyproject-toml/>`_.
+* :code:`ruff.toml`: Configuration for `Ruff <https://docs.astral.sh/ruff/>`_ linter and formatter.
+    * For more please check :ref:`Style guide`.
+    * We use `Ruff extension <https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff>`_ in VSCode to lint and format the code.
+* :code:`LICENSE`: License of the project. Here are some references
+    * `Licensing a repository <https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository>`_.
+    * `Adding a license to a repository on GitHub <https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository>`_.
+    * Adding a license on VSCode with extention `Choose a License extension <https://marketplace.visualstudio.com/items?itemName=ultram4rine.vscode-choosealicense>`_.
+* :code:`README.md`: Main page of the project including
+    * Brief description of the project.
+    * Installation instructions.
+    * A quick example.
+* :code:`CODE_OF_CONDUCT.md`: Code of conduct of the project.
+    * `Adding a code of conduct to your project <https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project>`_.

pyproject.toml

@@ -24,4 +24,4 @@ test = ["pytest", "pytest-cov"]
 docs = ["sphinx", "sphinx-autodoc-typehints", "furo"]
 
 [project.urls]
-github = "https://github.com/ihmeuw-msca/pypkg"
+github = "https://github.com/ihmeuw-msca/pypkg"