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 are
+welcome to make the project better, whether it's fixing bugs, adding new
+features, or improving documentation.
+
+.. important::
+
+    This project adheres to the `Contributor Covenant Code of Conduct`_. By
+    participating, you agree to uphold this code.
+
+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, suggesting 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 guides.
+
+    .. 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,182 @@
+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.
+
+    .. grid-item-card:: :fa:`vial-circle-check` Run the tests
+        :padding: 2 2 2 2
+        :link: run-tests
+        :link-type: ref
+
+        Verify your changes by testing the project.
+
+
+.. _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 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/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 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/pyworkbench
+
+.. note::
+
+    If you are not an Ansys employee, you need to fork the repository and
+    replace ``ansys`` with your GitHub user name in the ``git clone`` command.
+
+.. _install-for-developers:
+
+Install for developers
+======================
+
+Installing pyworkbench 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::
+
+    cd pyworkbench
+
+Then, create a new virtual environment named ``.venv`` to isolate your system's
+Python environment by running:
+
+.. code-block:: text
+
+    python -m venv .venv
+
+Finally, activate this environment by running:
+
+.. 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 by running:
+
+.. 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. To install Tox, run:
+
+.. code-block:: text
+
+    python -m pip install tox
+
+Finally, verify the 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
+modifications did not break the project. pyworkbench tests support different markers
+to avoid running the whole suite of tests. These markers are associated to a
+dedicated `Tox`_ environment.
+
+.. code-block:: text
+
+    tox -e tests

doc/source/contribute/documentarian.rst

@@ -0,0 +1,141 @@
+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
+
+        Explain 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
+
+        Showcase the capabilities of PyWorkbench by adding a new example.
+
+    .. 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
+===================
+
+The documentation generator used in PyWorkbench is `Sphinx`_. Most of the documents
+are written in `reStructuredText`_. Some parts of the documentation, like the
+:ref:`examples <Examples>`, use mix of `markdown`_ and Python. If
+you are interested in writing examples, see the :ref:`writing examples <write-examples>`
+section.
+
+The documentation is located in the ``doc/source`` directory. The landing page
+is declared in the ``doc/source/index.rst`` file. The rest of the files contain
+the main pages of different sections of the documentation. 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 slug of the
+online documentation. For example, the
+``doc/source/contribute/documentarian.rst`` renders as
+``https://workbench.docs.pyansys.com/contribute/documentarian``.
+
+Thus, if you create a new 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
+
+All files need to be included in a table of contents. No dangling files are
+permitted. If a file is not included in the table of contents, Sphinx raises a
+warning that makes 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, and building the documentation
+in different formats such as HTML. , and running the tests. The following
+environments are available:
+
+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