========================
Extending documentation
========================
We are working hard to ensure all aspects of the framework are well-documented. If you identify any gaps
in the documentation, you can help us fill them!


Sphinx and reStructuredText
-----------------------------
This documentation is generated by `Sphinx <https://www.sphinx-doc.org/en/master/usage/quickstart.html>`_
using `reStructuredText <https://docutils.sourceforge.io/rst.html>`_ markup language. Please refer to their
documentation for detailed syntax and features.

Documentation structure
------------------------
All documentation sources are located in the :code:`docs/` directory with the following structure:

:code:`api_docs/` - Auto-generated API documentation for all QLTY modules, classes, and functions

:code:`guides/` - User guides covering environment setup, running tests, integrations, and features

:code:`images/` - Images and screenshots used in the documentation

:code:`_static/` - Custom CSS, JavaScript, and other static assets (including theme customization)

:code:`_build/html/` - Generated HTML output (not committed to version control)

Build the documentation
------------------------
To build the documentation locally, navigate to the docs directory and run:

.. code-block:: bash

    cd docs
    sphinx-build -b html . _build/html

This generates HTML documentation in :code:`_build/html/`. Open :code:`_build/html/index.html` in your browser to view.

.. note::

    You need to have Sphinx installed in your Python environment:

    .. code-block:: bash

        pip install sphinx sphinx-rtd-theme

Clean build
-----------
If you need to rebuild from scratch (recommended after structural changes):

.. code-block:: bash

    cd docs
    rm -rf _build/html
    sphinx-build -b html . _build/html

How to document your code
---------------------------
We are using a sphinx module called :code:`autodoc` that retrieves all the docstring for a given module.
Here is an example of how you can document a method in a module:

.. code-block:: python

    def get_elements(self, locator):
    """
        Retrieves a list of elements that match the query. It first tries to verify that at least one element is
        present in the view.

        :param locator: A tuple of By or MobileBy and a string e.g.

            .. code-block:: python

                (By.XPATH, '//android.widget.Button[@resource-id="oaapprove"]')

        :type locator: tuple
        :return: A list of web elements that matched the query
        :rtype: list
    """

Describe your method parameters by using :code:`:param arg_name: Description`

Describe your parameter type by using :code:`:type arg_name: parameter_type`

Describe your return value by using :code:`:return: Description`

And describe your return value type by using :code:`:rtype: return_parameter_type`

The text inside the docstring is interpreted as reStructuredText so any directives can be used like code blocks or lists

The example above generates the following documentation:

.. image:: ../images/example_doc_output.png
    :align: center

You can also add documentation to your class or module level variables by adding a colon :code:`:` right after the :code:`#` sign:

.. code-block:: python

    #: Defines if the test run should send a message through slack to a specific channel
    SLACK_REPORTING = False

Adding new modules to documentation
------------------------------------
To add a new module to the API documentation:

1. **Create the module** in the appropriate directory within :code:`qlty/`

2. **Document your code** using docstrings (see "How to document your code" section above)

3. **Add to sys.path** if needed. Edit :code:`docs/conf.py` to include new directories:

   .. code-block:: python

       sys.path.append(os.path.abspath('../qlty'))
       sys.path.append(os.path.abspath('../qlty/classes'))
       sys.path.append(os.path.abspath('../qlty/utilities'))

4. **Create or update RST file** in :code:`docs/api_docs/` to reference your module:

   .. code-block:: rst

       My New Module
       -------------

       .. automodule:: my_new_module
          :members:
          :undoc-members:
          :show-inheritance:

5. **Add to index** by including your RST file in :code:`docs/index.rst` under the API Documentation section

6. **Rebuild** the documentation to see your changes

Customizing the theme
---------------------
The documentation uses a custom theme based on Read the Docs. To modify the appearance:

**Edit colors and styling** in :code:`docs/_static/custom.css`

**Current brand colors:**

- Primary: :code:`#f62def` (pink/magenta)
- Secondary: :code:`#4750c8` (blue/purple)
- Background: :code:`#131927` (dark navy)

**Add fonts or other assets** by updating :code:`html_css_files` in :code:`docs/conf.py`:

.. code-block:: python

    html_css_files = [
        'https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600;700&family=Inter:wght@300;400;500;600;700&display=swap',
        'custom.css',
    ]

After making theme changes, rebuild the documentation to see your updates.