Welcome to Unittest2doc
====================================================

English | `中文 <index.zh.html>`_

Unittest2doc is a tool for converting Python unit test code into documentation. The unit test section in this documentation is generated using Unittest2doc.

Seeing is believing, let's learn how to use Unittest2doc through examples in this documentation.

Project repository: https://github.com/Fmajor/unittest2doc

The project structure is:

.. code-block::

   unittest2doc/            # Project root directory
     src/                   # Source code directory
       unittest2doc/        # Package directory
         __init__.py
         unittest2doc.py
         ...
     sphinx-docs/           # Documentation directory
       source/              # Documentation source files
         conf.py            # Configuration file, import test packages here
         index.rst
         unittests/         # Unittest2doc will generate rst files here
         src/               # API documentation generated by sphinx autosummary
         ...
       build/               # Documentation build directory, run make html to generate this documentation
     tests/                 # Test directory, where we use Unittest2doc
       test_unittest2doc.py # Test file, including a Unittest2doc class and its running examples
       test_pformat_json.py # Here we test a function for structured JSON output
                            # For a structured output function, the best way to test is to display the results and save as documentation
     pyproject.toml
     README.rst

* In the project root directory, use ``make unittest``

  * Actually executes ``python -m unittest discover -s tests -p '*.py' -b``
  * This is general unit testing, we only care about the test results, not the test process

* In the project root directory, use ``make generate-unittest-docs``

  * Actually executes ``unittest2doc -s tests -p '*.py'``, which directly runs all test files that meet the conditions
  * Each test file can be executed individually, with runtime parameters that allow them to generate RST format sphinx documentation
    and save to the ``/sphinx-docs/source/unittests/`` directory, ultimately displayed in our documentation

Here we directly show the test files

``tests/test_unittest2doc.py``
------------------------------

Generated documentation: :doc:`/unittests/unittest2doc/unittest2doc/Unittest2Doc/index`

.. literalinclude:: ../../tests/test_unittest2doc.py
   :language: python
   :linenos:

``tests/test_pformat_json.py``
------------------------------

Generated documentation: :doc:`/unittests/unittest2doc/formatter/index`

.. literalinclude:: ../../tests/test_pformat_json.py
   :language: python
   :linenos:

``tests/test_exec_tool.py``
------------------------------

Generated documentation: :doc:`/unittests/unittest2doc/utils/exec_tool`

.. literalinclude:: ../../tests/test_exec_tool.py
   :language: python
   :linenos:

Finally, let's look at the generated documentation

* API documentation comes from our project source code, generated by sphinx's autosummary feature, which is not the focus of this article
* Unit test documentation comes from our test code, please explore the results yourself and compare with the test code

API Documentation and Unittests
-------------------------------

.. toctree::
   :maxdepth: 1

   catalogue