docs(contributing): basic layout

doc/changelog.d/199.documentation.md

@@ -0,0 +1 @@
+docs(contributing): basic layout

doc/source/conf.py

@@ -126,6 +126,7 @@
     "**/ExampleData*",
     "**/LaunchWorkbench*",
     "**/ClientWrapper*",
+    "links.rst",
 ]
 
 # additional logos for the latex coverpage
@@ -256,6 +257,7 @@ def get_file_size_in_mb(file_path):
 jinja_globals = {
     "SUPPORTED_PYTHON_VERSIONS": ["3.11", "3.12", "3.13"],
     "SUPPORTED_PLATFORMS": ["windows", "ubuntu"],
+    "PYWORKBENCH_VERSION": version,
 }
 
 jinja_contexts = {
@@ -275,3 +277,8 @@ def get_file_size_in_mb(file_path):
         "source_hash": get_sha256_from_file(ARTIFACTS_SDIST),
     },
 }
+
+# Common content for every RST file such us links
+rst_epilog = ""
+links_filepath = pathlib.Path(__file__).parent.absolute() / "links.rst"
+rst_epilog += links_filepath.read_text(encoding="utf-8")

doc/source/contribute.rst

@@ -0,0 +1,45 @@
+Contribute
+##########
+
+Thank you for your interest in contributing to PyWorkbench. Contributions for
+making the project better can include fixing bugs, adding new features, and
+improving the documentation.
+
+.. important::
+
+    This project adheres to the `Contributor Covenant Code of Conduct`_. By
+    participating, you agree to uphold this code of conduct.
+
+Start by selecting your role in the project:
+
+.. grid:: 1 1 3 3
+
+    .. grid-item-card:: :fa:`user` User
+        :link: contribute/user
+        :link-type: doc
+        :padding: 2 2 2 2
+
+        Report bugs, suggest features, and ask questions.
+
+    .. grid-item-card:: :fa:`book` Documentarian
+        :link: contribute/documentarian
+        :link-type: doc
+        :padding: 2 2 2 2
+
+        Improve the documentation and write new content.
+
+    .. grid-item-card:: :fa:`laptop-code` Developer
+        :link: contribute/developer
+        :link-type: doc
+        :padding: 2 2 2 2
+
+        Fix bugs, add new features, and improve the codebase.
+
+.. toctree::
+    :hidden:
+    :maxdepth: 3
+    :caption: Contribute
+
+    User<contribute/user>
+    Documentarian<contribute/documentarian>
+    Developer<contribute/developer>

doc/source/contribute/developer.rst

@@ -0,0 +1,184 @@
+Contribute 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
+
+        Fork the project to create a copy.
+
+    .. grid-item-card:: :fa:`download` Clone the repository
+        :padding: 2 2 2 2
+        :link: clone-the-repository
+        :link-type: ref
+
+        Clone the repository to download the copy to 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.
+
+    .. grid-item-card:: :fa:`vial-circle-check` Run the tests
+        :padding: 2 2 2 2
+        :link: run-tests
+        :link-type: ref
+
+        Verify your changes to the project by running tests.
+
+
+.. _fork-the-repository:
+
+Fork the repository
+===================
+
+Forking the repository is the first step to contributing to the project. This
+allows you to have your own copy of the project so that you can make changes without
+affecting 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/pyworkbench/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 that 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 on your machine.
+
+Clone the repository using SSH:
+
+.. code-block:: bash
+
+    git clone [email protected]:ansys/pyworkbench
+
+.. note::
+
+    If you are not an Ansys employee, you must fork the repository and
+    replace ``ansys`` with your GitHub username in the ``git clone`` command.
+
+.. _install-for-developers:
+
+Install for developers
+======================
+
+Installing PyWorkbench in development mode lets you change the code
+and see these 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:
+
+.. code-block::
+
+    cd pyworkbench
+
+Then, create a new virtual environment named ``.venv`` to isolate your system's
+Python environment:
+
+.. code-block:: text
+
+    python -m venv .venv
+
+Finally, activate this environment:
+
+.. tab-set::
+
+    .. tab-item:: Windows
+
+        .. tab-set::
+
+            .. tab-item:: CMD
+
+                .. code-block:: text
+
+                    .venv\Scripts\activate.bat
+
+            .. tab-item:: PowerShell
+
+                .. code-block:: text
+
+                    .venv\Scripts\Activate.ps1
+
+    .. tab-item:: macOS/Linux/UNIX
+
+        .. code-block:: text
+
+            source .venv/bin/activate
+
+Development mode
+----------------
+
+Now, install PyWorkbench in editable mode:
+
+.. code-block:: text
+
+    python -m pip install --editable .
+
+Verify the installation by checking the version of the library:
+
+
+.. code-block:: python
+
+    from ansys.workbench.core import __version__
+
+
+    print(f"pyworkbench version is {__version__}")
+
+.. jinja::
+
+    .. code-block:: text
+
+       >>> pyworkbench version is {{ PYWORKBENCH_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.
+
+Install Tox:
+
+.. code-block:: text
+
+    python -m pip install tox
+
+Verify the Tox installation by listing all the different environments
+(automation rules) for PyWorkbench:
+
+.. code-block:: text
+
+    tox list
+
+.. _run-tests:
+
+Run the tests
+=============
+
+Once you have made your changes, you can run the tests to verify that your
+changes did not break the project. PyWorkbench tests support different markers
+to avoid running the whole suite of tests. These markers are associated with a
+dedicated Tox environment.
+
+.. code-block:: text
+
+    tox -e tests

doc/source/contribute/documentarian.rst

@@ -0,0 +1,139 @@
+Contributing as a documentarian
+###############################
+
+.. grid:: 1 1 3 3
+
+    .. grid-item-card:: :fa:`pencil` Write documentation
+        :padding: 2 2 2 2
+        :link: write-documentation
+        :link-type: ref
+
+        Learn how to get started, use, and contribute to the project.
+
+    .. grid-item-card:: :fa:`laptop-code` Add a new example
+        :padding: 2 2 2 2
+        :link: write-examples
+        :link-type: ref
+
+        Write a new example to showcase the capabilities of PyWorkbench.
+
+    .. grid-item-card:: :fa:`file-code` Build the documentation
+        :padding: 2 2 2 2
+        :link: build-documentation
+        :link-type: ref
+
+        Render the documentation to see your changes reflected.
+
+.. _write-documentation:
+
+Write documentation
+===================
+
+`Sphinx`_ is the tool used to generate PyWorkbench documentation. You write most of the content
+in `ReStructuredText`_ files. However, some of the content, like the
+:ref:`examples <Examples>`, use a mix of `Markdown`_ and Python. If
+you are interested in writing examples, see :ref:`writing examples <write-examples>`.
+
+The documentation is located in the ``doc/source`` directory. The landing page
+is declared in the ``doc/source/index.rst`` file. The subdirectories contain
+the pages of different documentation sections. Finally, the
+``doc/source/_static/`` folder contains various assets like images, and CSS
+files.
+
+The layout of the ``doc/source`` directory is reflected in the URLs of the
+online documentation pages. For example, the
+``doc/source/contribute/documentarian.rst``file renders as
+``https://workbench.docs.pyansys.com/contribute/documentarian`` URL.
+
+Thus, if you create a file, it important to follow these rules:
+
+- Use lowercase letters for file and directory names.
+- Use short and descriptive names.
+- Use hyphens to separate words.
+- Play smart with the hierarchy of the files and directories.
+
+You must include all files in a table of contents. No orphan files are
+permitted. If a file is not included in the table of contents, Sphinx raises a
+warning that causes the build to fail.
+
+A table of contents can be declared using a directive like this:
+
+.. code-block:: rst
+
+    .. toctree::
+        :hidden:
+        :maxdepth: 3
+
+        path-to-file-A
+        path-to-file-B
+        path-to-file-C
+        ...
+
+The path to the file is relative to the directory where the table of contents
+is declared.
+
+.. _write-examples:
+
+Write a new example
+===================
+
+The :ref:`examples <Examples>` section of the documentation showcases different
+capabilities of PyWorkbench. Each example is a standalone Python script. Despite
+being PY files, they are written in a mix of `Markdown`_ and Python. This
+is possible thanks to the `myst-parser`_ Sphinx extension. In addition, these
+Python files can be opened as Jupyter Notebooks thanks to the `jupytext`_
+extension.
+
+Documentarians writing new examples are encouraged to open a new Jupyter Lab
+session and write the example as a Jupyter Notebook. This way, the
+documentarian can test the code and see the output in real time. The created
+Jupyter Notebook gets stored as a Python file automatically.
+
+Note that the examples are contained in its own repository, which you can find
+in `PyWorkbench examples repository`_.
+
+Finally, here are some tips for writing examples:
+
+- Start the example with an explanation of the main topic. For example, if you
+  are discussing a certain orbital maneuver, explain what that maneuver
+  entails. Similarly, if an example is centered around satellite coverage,
+  provide an explanation of what coverage is. Try to use as many relevant
+  keywords as possible in this section to optimize for Search Engine
+  Optimization.
+
+- The second section of the example must be a problem statement. This statement
+  must include all of the parameters needed in the example, as well as a
+  description of what the example aims to determine. Write this section in an
+  imperative form.
+
+- Include an explanation with each code cell. In a Jupyter Notebook, this
+  entails adding a Markdown cell before each code cell. The explanations should
+  be included before, not after, the corresponding code.
+
+.. _build-documentation:
+
+Build the documentation
+=======================
+
+`Tox`_ is used for automating the build of the documentation. There are
+different environments for cleaning the build, building the documentation
+in different formats such as HTML, and running the tests.
+
+The following environments are available:
+
+.. dropdown:: Documentation environments
+    :animate: fade-in
+    :icon: three-bars
+
+    .. list-table::
+        :header-rows: 1
+        :widths: auto
+
+        * - Environment
+          - Command
+        * - doc-style
+          - python -m tox -e doc-style
+        * - doc-links
+          - python -m tox -e doc-links
+        * - doc-html
+          - python -m tox -e html