From b55981cfa9244c01f229c5907df70e2ec2b01f90 Mon Sep 17 00:00:00 2001 From: Jon Crall Date: Thu, 1 Aug 2024 13:21:41 -0400 Subject: [PATCH] Update docs (#159) * Update docs structure and fixup some docstrings * Fix logo in docs --- docs/source/{ => auto}/modules.rst | 0 docs/source/auto/xdoctest.__main__.rst | 8 +++++++ docs/source/auto/xdoctest._tokenize.rst | 8 +++++++ docs/source/{ => auto}/xdoctest.checker.rst | 1 + docs/source/{ => auto}/xdoctest.constants.rst | 1 + docs/source/{ => auto}/xdoctest.core.rst | 1 + docs/source/{ => auto}/xdoctest.demo.rst | 1 + docs/source/{ => auto}/xdoctest.directive.rst | 1 + .../xdoctest.docstr.docscrape_google.rst | 1 + .../xdoctest.docstr.docscrape_numpy.rst | 1 + docs/source/{ => auto}/xdoctest.docstr.rst | 1 + .../{ => auto}/xdoctest.doctest_example.rst | 1 + .../{ => auto}/xdoctest.doctest_part.rst | 1 + .../{ => auto}/xdoctest.dynamic_analysis.rst | 1 + .../source/{ => auto}/xdoctest.exceptions.rst | 1 + .../{ => auto}/xdoctest.global_state.rst | 1 + docs/source/{ => auto}/xdoctest.parser.rst | 1 + docs/source/{ => auto}/xdoctest.plugin.rst | 1 + docs/source/{ => auto}/xdoctest.rst | 3 +++ docs/source/{ => auto}/xdoctest.runner.rst | 1 + .../{ => auto}/xdoctest.static_analysis.rst | 1 + docs/source/{ => auto}/xdoctest.utils.rst | 1 + .../xdoctest.utils.util_deprecation.rst | 1 + .../{ => auto}/xdoctest.utils.util_import.rst | 1 + .../{ => auto}/xdoctest.utils.util_misc.rst | 1 + .../{ => auto}/xdoctest.utils.util_mixins.rst | 1 + .../xdoctest.utils.util_notebook.rst | 1 + .../{ => auto}/xdoctest.utils.util_path.rst | 1 + .../{ => auto}/xdoctest.utils.util_str.rst | 1 + .../{ => auto}/xdoctest.utils.util_stream.rst | 1 + docs/source/conf.py | 2 +- docs/source/index.rst | 4 +--- .../source/{ => manual}/installing_python.rst | 0 .../source/{ => manual}/xdoc_with_jupyter.rst | 0 src/xdoctest/__init__.py | 19 ++++++++-------- src/xdoctest/checker.py | 18 ++++++++------- src/xdoctest/core.py | 22 +++++-------------- src/xdoctest/doctest_example.py | 2 +- 38 files changed, 73 insertions(+), 39 deletions(-) rename docs/source/{ => auto}/modules.rst (100%) create mode 100644 docs/source/auto/xdoctest.__main__.rst create mode 100644 docs/source/auto/xdoctest._tokenize.rst rename docs/source/{ => auto}/xdoctest.checker.rst (86%) rename docs/source/{ => auto}/xdoctest.constants.rst (87%) rename docs/source/{ => auto}/xdoctest.core.rst (85%) rename docs/source/{ => auto}/xdoctest.demo.rst (85%) rename docs/source/{ => auto}/xdoctest.directive.rst (87%) rename docs/source/{ => auto}/xdoctest.docstr.docscrape_google.rst (89%) rename docs/source/{ => auto}/xdoctest.docstr.docscrape_numpy.rst (89%) rename docs/source/{ => auto}/xdoctest.docstr.rst (93%) rename docs/source/{ => auto}/xdoctest.doctest_example.rst (88%) rename docs/source/{ => auto}/xdoctest.doctest_part.rst (87%) rename docs/source/{ => auto}/xdoctest.dynamic_analysis.rst (88%) rename docs/source/{ => auto}/xdoctest.exceptions.rst (87%) rename docs/source/{ => auto}/xdoctest.global_state.rst (87%) rename docs/source/{ => auto}/xdoctest.parser.rst (86%) rename docs/source/{ => auto}/xdoctest.plugin.rst (86%) rename docs/source/{ => auto}/xdoctest.rst (90%) rename docs/source/{ => auto}/xdoctest.runner.rst (86%) rename docs/source/{ => auto}/xdoctest.static_analysis.rst (88%) rename docs/source/{ => auto}/xdoctest.utils.rst (95%) rename docs/source/{ => auto}/xdoctest.utils.util_deprecation.rst (89%) rename docs/source/{ => auto}/xdoctest.utils.util_import.rst (88%) rename docs/source/{ => auto}/xdoctest.utils.util_misc.rst (88%) rename docs/source/{ => auto}/xdoctest.utils.util_mixins.rst (88%) rename docs/source/{ => auto}/xdoctest.utils.util_notebook.rst (89%) rename docs/source/{ => auto}/xdoctest.utils.util_path.rst (88%) rename docs/source/{ => auto}/xdoctest.utils.util_str.rst (88%) rename docs/source/{ => auto}/xdoctest.utils.util_stream.rst (88%) rename docs/source/{ => manual}/installing_python.rst (100%) rename docs/source/{ => manual}/xdoc_with_jupyter.rst (100%) diff --git a/docs/source/modules.rst b/docs/source/auto/modules.rst similarity index 100% rename from docs/source/modules.rst rename to docs/source/auto/modules.rst diff --git a/docs/source/auto/xdoctest.__main__.rst b/docs/source/auto/xdoctest.__main__.rst new file mode 100644 index 00000000..77e26cd0 --- /dev/null +++ b/docs/source/auto/xdoctest.__main__.rst @@ -0,0 +1,8 @@ +xdoctest.\_\_main\_\_ module +============================ + +.. automodule:: xdoctest.__main__ + :members: + :undoc-members: + :show-inheritance: + :private-members: diff --git a/docs/source/auto/xdoctest._tokenize.rst b/docs/source/auto/xdoctest._tokenize.rst new file mode 100644 index 00000000..8a1deb93 --- /dev/null +++ b/docs/source/auto/xdoctest._tokenize.rst @@ -0,0 +1,8 @@ +xdoctest.\_tokenize module +========================== + +.. automodule:: xdoctest._tokenize + :members: + :undoc-members: + :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.checker.rst b/docs/source/auto/xdoctest.checker.rst similarity index 86% rename from docs/source/xdoctest.checker.rst rename to docs/source/auto/xdoctest.checker.rst index 16d3cf93..d6ef01d2 100644 --- a/docs/source/xdoctest.checker.rst +++ b/docs/source/auto/xdoctest.checker.rst @@ -5,3 +5,4 @@ xdoctest.checker module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.constants.rst b/docs/source/auto/xdoctest.constants.rst similarity index 87% rename from docs/source/xdoctest.constants.rst rename to docs/source/auto/xdoctest.constants.rst index 1647df93..fed9431f 100644 --- a/docs/source/xdoctest.constants.rst +++ b/docs/source/auto/xdoctest.constants.rst @@ -5,3 +5,4 @@ xdoctest.constants module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.core.rst b/docs/source/auto/xdoctest.core.rst similarity index 85% rename from docs/source/xdoctest.core.rst rename to docs/source/auto/xdoctest.core.rst index 287eb439..bdc6857b 100644 --- a/docs/source/xdoctest.core.rst +++ b/docs/source/auto/xdoctest.core.rst @@ -5,3 +5,4 @@ xdoctest.core module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.demo.rst b/docs/source/auto/xdoctest.demo.rst similarity index 85% rename from docs/source/xdoctest.demo.rst rename to docs/source/auto/xdoctest.demo.rst index 19d2670f..e95061f1 100644 --- a/docs/source/xdoctest.demo.rst +++ b/docs/source/auto/xdoctest.demo.rst @@ -5,3 +5,4 @@ xdoctest.demo module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.directive.rst b/docs/source/auto/xdoctest.directive.rst similarity index 87% rename from docs/source/xdoctest.directive.rst rename to docs/source/auto/xdoctest.directive.rst index 7154d7a8..729c4573 100644 --- a/docs/source/xdoctest.directive.rst +++ b/docs/source/auto/xdoctest.directive.rst @@ -5,3 +5,4 @@ xdoctest.directive module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.docstr.docscrape_google.rst b/docs/source/auto/xdoctest.docstr.docscrape_google.rst similarity index 89% rename from docs/source/xdoctest.docstr.docscrape_google.rst rename to docs/source/auto/xdoctest.docstr.docscrape_google.rst index 2a947708..b378642f 100644 --- a/docs/source/xdoctest.docstr.docscrape_google.rst +++ b/docs/source/auto/xdoctest.docstr.docscrape_google.rst @@ -5,3 +5,4 @@ xdoctest.docstr.docscrape\_google module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.docstr.docscrape_numpy.rst b/docs/source/auto/xdoctest.docstr.docscrape_numpy.rst similarity index 89% rename from docs/source/xdoctest.docstr.docscrape_numpy.rst rename to docs/source/auto/xdoctest.docstr.docscrape_numpy.rst index 7004ccae..16a00426 100644 --- a/docs/source/xdoctest.docstr.docscrape_numpy.rst +++ b/docs/source/auto/xdoctest.docstr.docscrape_numpy.rst @@ -5,3 +5,4 @@ xdoctest.docstr.docscrape\_numpy module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.docstr.rst b/docs/source/auto/xdoctest.docstr.rst similarity index 93% rename from docs/source/xdoctest.docstr.rst rename to docs/source/auto/xdoctest.docstr.rst index c4cfe2df..1163f589 100644 --- a/docs/source/xdoctest.docstr.rst +++ b/docs/source/auto/xdoctest.docstr.rst @@ -17,3 +17,4 @@ Module contents :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.doctest_example.rst b/docs/source/auto/xdoctest.doctest_example.rst similarity index 88% rename from docs/source/xdoctest.doctest_example.rst rename to docs/source/auto/xdoctest.doctest_example.rst index 5b6b2dc9..316e429e 100644 --- a/docs/source/xdoctest.doctest_example.rst +++ b/docs/source/auto/xdoctest.doctest_example.rst @@ -5,3 +5,4 @@ xdoctest.doctest\_example module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.doctest_part.rst b/docs/source/auto/xdoctest.doctest_part.rst similarity index 87% rename from docs/source/xdoctest.doctest_part.rst rename to docs/source/auto/xdoctest.doctest_part.rst index 5de5128e..759aa444 100644 --- a/docs/source/xdoctest.doctest_part.rst +++ b/docs/source/auto/xdoctest.doctest_part.rst @@ -5,3 +5,4 @@ xdoctest.doctest\_part module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.dynamic_analysis.rst b/docs/source/auto/xdoctest.dynamic_analysis.rst similarity index 88% rename from docs/source/xdoctest.dynamic_analysis.rst rename to docs/source/auto/xdoctest.dynamic_analysis.rst index 9a5409e9..c8eb2b3f 100644 --- a/docs/source/xdoctest.dynamic_analysis.rst +++ b/docs/source/auto/xdoctest.dynamic_analysis.rst @@ -5,3 +5,4 @@ xdoctest.dynamic\_analysis module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.exceptions.rst b/docs/source/auto/xdoctest.exceptions.rst similarity index 87% rename from docs/source/xdoctest.exceptions.rst rename to docs/source/auto/xdoctest.exceptions.rst index 51d93172..a175b90f 100644 --- a/docs/source/xdoctest.exceptions.rst +++ b/docs/source/auto/xdoctest.exceptions.rst @@ -5,3 +5,4 @@ xdoctest.exceptions module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.global_state.rst b/docs/source/auto/xdoctest.global_state.rst similarity index 87% rename from docs/source/xdoctest.global_state.rst rename to docs/source/auto/xdoctest.global_state.rst index 4d82b7aa..49113a9c 100644 --- a/docs/source/xdoctest.global_state.rst +++ b/docs/source/auto/xdoctest.global_state.rst @@ -5,3 +5,4 @@ xdoctest.global\_state module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.parser.rst b/docs/source/auto/xdoctest.parser.rst similarity index 86% rename from docs/source/xdoctest.parser.rst rename to docs/source/auto/xdoctest.parser.rst index 0a479186..5cd57a2d 100644 --- a/docs/source/xdoctest.parser.rst +++ b/docs/source/auto/xdoctest.parser.rst @@ -5,3 +5,4 @@ xdoctest.parser module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.plugin.rst b/docs/source/auto/xdoctest.plugin.rst similarity index 86% rename from docs/source/xdoctest.plugin.rst rename to docs/source/auto/xdoctest.plugin.rst index a062d3ed..8b71382f 100644 --- a/docs/source/xdoctest.plugin.rst +++ b/docs/source/auto/xdoctest.plugin.rst @@ -5,3 +5,4 @@ xdoctest.plugin module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.rst b/docs/source/auto/xdoctest.rst similarity index 90% rename from docs/source/xdoctest.rst rename to docs/source/auto/xdoctest.rst index c0410aba..972d2db0 100644 --- a/docs/source/xdoctest.rst +++ b/docs/source/auto/xdoctest.rst @@ -16,6 +16,8 @@ Submodules .. toctree:: :maxdepth: 4 + xdoctest.__main__ + xdoctest._tokenize xdoctest.checker xdoctest.constants xdoctest.core @@ -38,3 +40,4 @@ Module contents :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.runner.rst b/docs/source/auto/xdoctest.runner.rst similarity index 86% rename from docs/source/xdoctest.runner.rst rename to docs/source/auto/xdoctest.runner.rst index 39ea382c..060980f4 100644 --- a/docs/source/xdoctest.runner.rst +++ b/docs/source/auto/xdoctest.runner.rst @@ -5,3 +5,4 @@ xdoctest.runner module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.static_analysis.rst b/docs/source/auto/xdoctest.static_analysis.rst similarity index 88% rename from docs/source/xdoctest.static_analysis.rst rename to docs/source/auto/xdoctest.static_analysis.rst index ce57f6b3..dbf66507 100644 --- a/docs/source/xdoctest.static_analysis.rst +++ b/docs/source/auto/xdoctest.static_analysis.rst @@ -5,3 +5,4 @@ xdoctest.static\_analysis module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.utils.rst b/docs/source/auto/xdoctest.utils.rst similarity index 95% rename from docs/source/xdoctest.utils.rst rename to docs/source/auto/xdoctest.utils.rst index 21579a5d..fb974640 100644 --- a/docs/source/xdoctest.utils.rst +++ b/docs/source/auto/xdoctest.utils.rst @@ -23,3 +23,4 @@ Module contents :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.utils.util_deprecation.rst b/docs/source/auto/xdoctest.utils.util_deprecation.rst similarity index 89% rename from docs/source/xdoctest.utils.util_deprecation.rst rename to docs/source/auto/xdoctest.utils.util_deprecation.rst index cf83cc7a..eb748974 100644 --- a/docs/source/xdoctest.utils.util_deprecation.rst +++ b/docs/source/auto/xdoctest.utils.util_deprecation.rst @@ -5,3 +5,4 @@ xdoctest.utils.util\_deprecation module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.utils.util_import.rst b/docs/source/auto/xdoctest.utils.util_import.rst similarity index 88% rename from docs/source/xdoctest.utils.util_import.rst rename to docs/source/auto/xdoctest.utils.util_import.rst index 8fd1797f..8f3cd927 100644 --- a/docs/source/xdoctest.utils.util_import.rst +++ b/docs/source/auto/xdoctest.utils.util_import.rst @@ -5,3 +5,4 @@ xdoctest.utils.util\_import module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.utils.util_misc.rst b/docs/source/auto/xdoctest.utils.util_misc.rst similarity index 88% rename from docs/source/xdoctest.utils.util_misc.rst rename to docs/source/auto/xdoctest.utils.util_misc.rst index 3076dbd9..b0825640 100644 --- a/docs/source/xdoctest.utils.util_misc.rst +++ b/docs/source/auto/xdoctest.utils.util_misc.rst @@ -5,3 +5,4 @@ xdoctest.utils.util\_misc module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.utils.util_mixins.rst b/docs/source/auto/xdoctest.utils.util_mixins.rst similarity index 88% rename from docs/source/xdoctest.utils.util_mixins.rst rename to docs/source/auto/xdoctest.utils.util_mixins.rst index a14a4319..46eb676e 100644 --- a/docs/source/xdoctest.utils.util_mixins.rst +++ b/docs/source/auto/xdoctest.utils.util_mixins.rst @@ -5,3 +5,4 @@ xdoctest.utils.util\_mixins module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.utils.util_notebook.rst b/docs/source/auto/xdoctest.utils.util_notebook.rst similarity index 89% rename from docs/source/xdoctest.utils.util_notebook.rst rename to docs/source/auto/xdoctest.utils.util_notebook.rst index 7a891426..88b854c7 100644 --- a/docs/source/xdoctest.utils.util_notebook.rst +++ b/docs/source/auto/xdoctest.utils.util_notebook.rst @@ -5,3 +5,4 @@ xdoctest.utils.util\_notebook module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.utils.util_path.rst b/docs/source/auto/xdoctest.utils.util_path.rst similarity index 88% rename from docs/source/xdoctest.utils.util_path.rst rename to docs/source/auto/xdoctest.utils.util_path.rst index e7c39cb3..b61473de 100644 --- a/docs/source/xdoctest.utils.util_path.rst +++ b/docs/source/auto/xdoctest.utils.util_path.rst @@ -5,3 +5,4 @@ xdoctest.utils.util\_path module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.utils.util_str.rst b/docs/source/auto/xdoctest.utils.util_str.rst similarity index 88% rename from docs/source/xdoctest.utils.util_str.rst rename to docs/source/auto/xdoctest.utils.util_str.rst index b75b041a..81b6fd97 100644 --- a/docs/source/xdoctest.utils.util_str.rst +++ b/docs/source/auto/xdoctest.utils.util_str.rst @@ -5,3 +5,4 @@ xdoctest.utils.util\_str module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/xdoctest.utils.util_stream.rst b/docs/source/auto/xdoctest.utils.util_stream.rst similarity index 88% rename from docs/source/xdoctest.utils.util_stream.rst rename to docs/source/auto/xdoctest.utils.util_stream.rst index bb2aa994..6c4aec7a 100644 --- a/docs/source/xdoctest.utils.util_stream.rst +++ b/docs/source/auto/xdoctest.utils.util_stream.rst @@ -5,3 +5,4 @@ xdoctest.utils.util\_stream module :members: :undoc-members: :show-inheritance: + :private-members: diff --git a/docs/source/conf.py b/docs/source/conf.py index bd984742..adab4d5d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -17,7 +17,7 @@ # need to edit the conf.py cd ~/code/xdoctest/docs - sphinx-apidoc --private --separate -f -o ~/code/xdoctest/docs/source/auto ~/code/xdoctest/src/xdoctest '_tokenize.py' + sphinx-apidoc --private --separate --force --output-dir ~/code/xdoctest/docs/source/auto ~/code/xdoctest/src/xdoctest '_tokenize.py' # Note: the module should importable before running this # (e.g. install it in developer mode or munge the PYTHONPATH) diff --git a/docs/source/index.rst b/docs/source/index.rst index 51cf94c5..a9cb08a9 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,5 +1,3 @@ -.. This file is no longer used, we redirect to autoapi/xdoctest/index.html - :github_url: https://github.com/Erotemic/xdoctest .. The __init__ files contains the top-level documentation overview @@ -10,7 +8,7 @@ :maxdepth: 8 :caption: Package Layout - xdoctest + auto/xdoctest Indices and tables diff --git a/docs/source/installing_python.rst b/docs/source/manual/installing_python.rst similarity index 100% rename from docs/source/installing_python.rst rename to docs/source/manual/installing_python.rst diff --git a/docs/source/xdoc_with_jupyter.rst b/docs/source/manual/xdoc_with_jupyter.rst similarity index 100% rename from docs/source/xdoc_with_jupyter.rst rename to docs/source/manual/xdoc_with_jupyter.rst diff --git a/src/xdoctest/__init__.py b/src/xdoctest/__init__.py index 2b7f48e3..a9031715 100644 --- a/src/xdoctest/__init__.py +++ b/src/xdoctest/__init__.py @@ -1,8 +1,8 @@ # :github_url: https://github.com/Erotemic/xdoctest ''' -.. The large version wont work because github strips rst image rescaling. https://i.imgur.com/AcWVroL.png -.. image:: https://camo.githubusercontent.com/505298c88719d26f35794319bbc39a522e674314/68747470733a2f2f692e696d6775722e636f6d2f7530745959784d2e706e67 +.. The large version wont work because github strips rst image rescaling. https://i.imgur.com/u0tYYxM.png +.. image:: https://i.imgur.com/u0tYYxM.png :height: 100px :align: left @@ -56,8 +56,9 @@ Getting Started 0: Installation -------------------------------- -First ensure that you have :doc:`Python installed <../../installing_python>` and -ideally are in a virtual environment. Install xdoctest using the pip. +First ensure that you have +:doc:`Python installed <../manual/installing_python>` and ideally are in a +virtual environment. Install xdoctest using the pip. .. code:: bash @@ -94,7 +95,6 @@ def fib(n): a, b = b, a+b print() - We can add a "doctest" in the "docstring" as both an example and a test of the code. All we have to do is prefix the doctest code with three right chevrons `` >>> ``. We can also use xdoctest directives to control the flow of doctest @@ -127,10 +127,9 @@ def fib(n): ``xdoctest/__init__.py`` file, which is a Python file, that means we can write doctests in it. If you have xdoctest installed, you can use the xdoctest cli to execute the following code: ``xdoctest -m xdoctest.__init__ __doc__:0``. -Also notice that the previous code prefixed with ``>>> `` is skipped due to the -xdoctest ``SKIP`` :doc:`directive`. For more information on -directives see :doc:`the docs for the xdoctest directive -module`. +Also notice that the previous doctest is skipped due to the SKIP directive. +For more information on directives see +:doc:`the docs for the xdoctest directive module`. .. code:: python @@ -305,7 +304,7 @@ def fib(n): You can also run doctests -:doc:`inside Jupyter Notebooks <../xdoc_with_jupyter>`. +:doc:`inside Jupyter Notebooks <../manual/xdoc_with_jupyter>`. ''' diff --git a/src/xdoctest/checker.py b/src/xdoctest/checker.py index e1032e62..4a26674c 100644 --- a/src/xdoctest/checker.py +++ b/src/xdoctest/checker.py @@ -14,21 +14,23 @@ A doctest that uses stdout might look like this ->>> print('We expect this exact string') -We expect this exact string +.. code:: python + + >>> print('We expect this exact string') + We expect this exact string A doctest that uses a raw expression might look like this ->>> def foo(): ->>> return 3 ->>> foo() -3 +.. code:: python + + >>> def foo(): + >>> return 3 + >>> foo() + 3 In most cases it is best to use stdout to write your got-want tests because it is easier to control strings sent to stdout than it is to control the representation of expression-based "got-strings". - - """ import re import difflib diff --git a/src/xdoctest/core.py b/src/xdoctest/core.py index c1a4e858..b529368b 100644 --- a/src/xdoctest/core.py +++ b/src/xdoctest/core.py @@ -5,29 +5,19 @@ The following is a glossary of terms and jargon used in this repo. -* callname - the name of a callable function, method, class etc... e.g. - ``myfunc``, ``MyClass``, or ``MyClass.some_method``. +* callname - the name of a callable function, method, class etc... e.g. ``myfunc``, ``MyClass``, or ``MyClass.some_method``. -* got / want - a test that produces stdout or a value to check. Whatever is - produced is what you "got" and whatever is expected is what you "want". - See :mod:`xdoctest.checker` for more details. +* got / want - a test that produces stdout or a value to check. Whatever is produced is what you "got" and whatever is expected is what you "want". See :mod:`xdoctest.checker` for more details. -* directives - special in-doctest comments that change the behavior of the - doctests at runtime. See :mod:`xdoctest.directive` for more details. +* directives - special in-doctest comments that change the behavior of the doctests at runtime. See :mod:`xdoctest.directive` for more details. -* chevrons - the three cheverons (``>>> ``) or right angle brakets are the - standard prefix for a doctest, also referred to as a PS1 line in the - parser. +* chevrons - the three cheverons (``>>> ``) or right angle brakets are the standard prefix for a doctest, also referred to as a PS1 line in the parser. * zero-args - a function that can be called without any arguments. -* freeform style - This is the term used to refer to a doctest that could be - anywhere in the docstring. The alternative are structured doctests where - they are only expected in known positions like in "Example blocks" for - google and numpy style docstrings. +* freeform style - This is the term used to refer to a doctest that could be anywhere in the docstring. The alternative are structured doctests where they are only expected in known positions like in "Example blocks" for google and numpy style docstrings. -* TODO - complete this list (Make an issue or PR if there is any term you don't - immediately understand!). +* TODO - complete this list (Make an issue or PR if there is any term you don't immediately understand!). """ import sys import textwrap diff --git a/src/xdoctest/doctest_example.py b/src/xdoctest/doctest_example.py index d69465fa..4995c508 100644 --- a/src/xdoctest/doctest_example.py +++ b/src/xdoctest/doctest_example.py @@ -499,7 +499,7 @@ def format_src(self, linenos=True, colored=None, want=True, offset_linenos (bool): if True offset line numbers to agree with their position in the source text file (default False). - prefix (bool): if False, exclude the doctest `>>> ` prefix + prefix (bool): if False, exclude the doctest ``>>> `` prefix Returns: str