docs: add contribute section (#636)

Co-authored-by: pyansys-ci-bot <[email protected]>
Co-authored-by: Jorge Martínez <[email protected]>
Co-authored-by: Maxime Rey <[email protected]>

Author: 4 people

.github/dependabot.yml

@@ -1,13 +1,17 @@
 version: 2
 updates:
-  - package-ecosystem: "pip" # See documentation for possible values
-    directory: "/" # Location of package manifests
+  - package-ecosystem: "pip"
+    directory: "/"
     insecure-external-code-execution: allow
     schedule:
       interval: "daily"
     labels:
       - "maintenance"
       - "dependencies"
+    assignees:
+      - "pyansys-ci-bot"
+    commit-message:
+      prefix: "build"
 
   - package-ecosystem: "github-actions"
     directory: "/"
@@ -19,3 +23,7 @@ updates:
       - "pyansys-ci-bot"
     commit-message:
       prefix: "ci"
+    groups:
+       actions:
+          patterns:
+            - "*"

.gitignore

@@ -28,6 +28,7 @@ share/python-wheels/
 .installed.cfg
 *.egg
 MANIFEST
+.DS_Store
 
 # PyInstaller
 #  Usually these files are written by a python script from a template

CONTRIBUTING.md

@@ -1,10 +1,16 @@
 # Contributing
 
-If you are interested in contributing to our project, please make sure to review
-our contribution guidelines, which are specified in the
-[PyAnsys Developer's Documentation - Contributing](https://dev.docs.pyansys.com/how-to/contributing.html) page. This document
-outlines the process for submitting issues, proposing changes, and making pull
-requests to our codebase. Following these guidelines will help ensure that your
-contributions are properly integrated and reviewed, and will help maintain the
-overall quality and consistency of the project. Thank you for your interest in
-contributing to our community.
+We absolutely welcome any code contributions and we hope that this
+guide will facilitate an understanding of the Ansys Sphinx theme code
+repository. It is important to note that while the Ansys Sphinx theme software
+package is maintained by ANSYS, Inc. and any submissions will be reviewed
+thoroughly before merging, we still seek to foster a community that can
+support user questions and develop new features to make this software
+a useful tool for all users. As such, we welcome and encourage any
+questions or submissions to this repository.
+
+For contributing to this project, please refer to the [PyAnsys Developer's Guide].
+Further information about contributing to Ansys Sphinx theme can be found in [Contributing].
+
+[PyAnsys Developer's Guide]: https://dev.docs.pyansys.com/index.html
+[Contributing]: https://sphinxdocs.ansys.com/version/dev/contribute.html

doc/changelog.d/636.documentation.md

@@ -0,0 +1 @@
+docs: add contribute section

doc/source/conf.py

@@ -3,6 +3,7 @@
 from datetime import datetime
 import os
 from pathlib import Path
+import subprocess
 from typing import List
 
 from github import Github
@@ -162,6 +163,11 @@
         "version": f"v{version}" if not version.endswith("dev0") else "main",
     },
     "pdf_guide": {"version": get_version_match(__version__)},  # noqa: E501
+    "toxenvs": {
+        "envs": subprocess.run(
+            ["tox", "list", "-d", "-q"], capture_output=True, text=True
+        ).stdout.splitlines()[1:],
+    },
 }
 
 
@@ -297,3 +303,8 @@ def download_and_process_files(example_links: List[str]) -> List[str]:
 
     jinja_contexts["examples"] = {"inputs_examples": file_names}
     jinja_contexts["admonitions"] = {"inputs_admonitions": admonitions_links}
+
+
+jinja_globals = {
+    "ANSYS_SPHINX_THEME_VERSION": version,
+}

doc/source/contribute.rst

@@ -0,0 +1,33 @@
+
+Contribute
+##########
+
+Thank you for your interest in contributing to Ansys Sphinx theme! Contributions are welcome
+to make the project better, whether it's fixing bugs, adding new features, or
+improving documentation. Below are the guidelines to follow when contributing.
+
+
+.. grid::
+    :gutter: 1 2 3 3
+    :padding: 1 2 3 3
+
+    .. grid-item-card:: :fa:`user` User
+        :link: contribute/user
+        :link-type: doc
+
+        Learn how to contribute as a user.
+
+    .. grid-item-card:: :fa:`code-fork` Developer
+        :link: contribute/developer
+        :link-type: doc
+
+        Learn how to contribute as a developer.
+
+
+.. toctree::
+    :hidden:
+    :maxdepth: 1
+    :caption: Contribute
+
+    User<contribute/user>
+    Developer<contribute/developer>

doc/source/contribute/developer.rst

@@ -0,0 +1,241 @@
+Contributing as a developer
+###########################
+
+.. grid:: 1 1 3 3
+
+    .. grid-item-card:: :fa:`code-fork` Fork the repository
+        :padding: 2 2 2 2
+        :link: fork-the-repository
+        :link-type: ref
+
+        Learn how to fork the project and get your own copy.
+
+    .. grid-item-card:: :fa:`download` Clone the repository
+        :padding: 2 2 2 2
+        :link: clone-the-repository
+        :link-type: ref
+
+        Download your own copy in your local machine.
+
+    .. grid-item-card:: :fa:`download` Install for developers
+        :padding: 2 2 2 2
+        :link: install-for-developers
+        :link-type: ref
+
+        Install the project in editable mode.
+
+
+.. _fork-the-repository:
+
+Fork the repository
+===================
+
+Forking the repository is the first step for contributing to the project. This
+allows you to have your own copy of the project so you can make changes without
+affection the main project. Once you have made your changes, you can submit a
+pull-request to the main project to have your changes reviewed and merged.
+
+.. button-link:: https://github.com/ansys/ansys-sphinx-theme/fork
+    :color: primary
+    :align: center
+
+    :fa:`code-fork` Fork this project
+
+.. note::
+
+    If you are an Ansys employee, you can skip this step.
+
+.. _clone-the-repository:
+
+Clone the repository
+====================
+
+Make sure you `configure SSH`_ with your GitHub
+account. This allows you to clone the repository without having to use tokens
+or passwords. Also, make sure you have `git`_ installed in your machine.
+
+To clone the repository using SSH, run:
+
+.. code-block:: bash
+
+    git clone [email protected]:ansys/ansys-sphinx-theme
+
+.. _install-for-developers:
+
+Install for developers
+======================
+
+Installing Ansys sphinx theme in development mode allows you to perform changes to the code
+and see the changes reflected in your environment without having to reinstall
+the library every time you make a change.
+
+Virtual environment
+-------------------
+
+Start by navigating to the project's root directory by running:
+
+.. code-block:: bash
+
+    cd ansys-sphinx-theme
+
+Then, create a new virtual environment named ``.venv`` to isolate your system's
+Python environment by running:
+
+.. code-block:: bash
+
+    python -m venv .venv
+
+Finally, activate this environment by running:
+
+.. tab-set::
+
+    .. tab-item:: Windows
+
+        .. tab-set::
+
+            .. tab-item:: CMD
+
+                .. code-block:: bash
+
+                    .venv\Scripts\activate.bat
+
+            .. tab-item:: PowerShell
+
+                .. code-block:: bash
+
+                    .venv\Scripts\Activate.ps1
+
+    .. tab-item:: macOS/Linux/UNIX
+
+        .. code-block:: bash
+
+            source .venv/bin/activate
+
+Development mode
+----------------
+
+Now, install Ansys sphinx theme in editable mode by running:
+
+.. code-block:: bash
+
+    python -m pip install --editable .
+
+Verify the installation by checking the version of the library:
+
+
+.. code-block:: python
+
+    from ansys_sphinx_theme import __version__
+    print(f"Ansys sphinx thenme version is {__version__}")
+
+.. jinja::
+
+    .. code-block:: bash
+
+       >>> Ansys sphinx theme version is {{ ANSYS_SPHINX_THEME_VERSION }}
+
+Install ``Tox``
+---------------
+
+Once the project is installed, you can install `Tox`_. This is a cross-platform
+automation tool. The main advantage of Tox is that it allows you to test your
+project in different environments and configurations in a temporary and
+isolated Python virtual environment. To install Tox, run:
+
+.. code-block:: bash
+
+    python -m pip install tox
+
+Finally, verify the installation by listing all the different environments
+(automation rules) for Ansys Sphinx theme:
+
+.. code-block:: bash
+
+    python -m tox list
+
+.. jinja:: toxenvs
+
+    .. dropdown:: Default Tox environments
+        :animate: fade-in
+        :icon: three-bars
+
+        .. list-table::
+            :header-rows: 1
+            :widths: auto
+
+            * - Environment
+              - Description
+              - usage
+            {% for environment in envs %}
+            {% set name, description  = environment.split("->") %}
+            * - {{ name }}
+              - {{ description }}
+              - python -m tox -e {{ name }}
+            {% endfor %}
+
+
+Adhere to code style
+--------------------
+
+Ansys Sphinx theme follows the PEP8 standard as outlined in
+`PEP 8 <https://dev.docs.pyansys.com/coding-style/pep8.html>`_ in
+the *PyAnsys Developer's Guide* and implements style checking using
+`pre-commit <https://pre-commit.com/>`_.
+
+To ensure your code meets minimum code styling standards, run these commands::
+
+  pip install pre-commit
+  pre-commit run --all-files
+
+or use tox as above::
+
+    tox -e code-style
+
+You can also install this as a pre-commit hook by running this command::
+
+  pre-commit install
+
+This way, it's not possible for you to push code that fails the style checks::
+
+  $ pre-commit install
+  $ git commit -am "added my cool feature"
+  ruff.....................................................................Passed
+  ruff-format..............................................................Passed
+  codespell................................................................Passed
+  prettier.................................................................Passed
+  check for merge conflicts................................................Passed
+  debug statements (python)................................................Passed
+  check yaml...............................................................Passed
+  trim trailing whitespace.................................................Passed
+  Validate GitHub Workflows................................................Passed
+  Add License Headers......................................................Passed
+
+
+Build the documentation
+-----------------------
+
+To build documentation locally, you can either use Tox as mentioned above or
+run the following commands:
+
+1. Install the required dependencies by running::
+
+    python -m pip install -e .[doc]
+
+2. Build the documentation by running::
+
+    # On Linux or macOS
+    make -C doc/ html
+
+    # On Windows
+    doc\make.bat html
+
+3. The documentation is built in the ``doc/_build/html`` directory. Open the
+   ``index.html`` file in your browser to view the documentation.
+
+You can clean the build directory by running::
+
+    # On Linux or macOS
+    make -C doc/ clean
+
+    # On Windows
+    doc\make.bat clean