Update docs (#159)

* Update docs structure and fixup some docstrings

* Fix logo in docs

docs/source/auto/xdoctest.__main__.rst

@@ -0,0 +1,8 @@
+xdoctest.\_\_main\_\_ module
+============================
+
+.. automodule:: xdoctest.__main__
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:

docs/source/auto/xdoctest._tokenize.rst

@@ -0,0 +1,8 @@
+xdoctest.\_tokenize module
+==========================
+
+.. automodule:: xdoctest._tokenize
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:

docs/source/xdoctest.checker.rst → docs/source/auto/xdoctest.checker.rst

@@ -5,3 +5,4 @@ xdoctest.checker module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.constants.rst → docs/source/auto/xdoctest.constants.rst

@@ -5,3 +5,4 @@ xdoctest.constants module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.core.rst → docs/source/auto/xdoctest.core.rst

@@ -5,3 +5,4 @@ xdoctest.core module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.demo.rst → docs/source/auto/xdoctest.demo.rst

@@ -5,3 +5,4 @@ xdoctest.demo module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.directive.rst → docs/source/auto/xdoctest.directive.rst

@@ -5,3 +5,4 @@ xdoctest.directive module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.docstr.docscrape_google.rst → docs/source/auto/xdoctest.docstr.docscrape_google.rst

@@ -5,3 +5,4 @@ xdoctest.docstr.docscrape\_google module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.docstr.docscrape_numpy.rst → docs/source/auto/xdoctest.docstr.docscrape_numpy.rst

@@ -5,3 +5,4 @@ xdoctest.docstr.docscrape\_numpy module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.docstr.rst → docs/source/auto/xdoctest.docstr.rst

@@ -17,3 +17,4 @@ Module contents
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.doctest_example.rst → docs/source/auto/xdoctest.doctest_example.rst

@@ -5,3 +5,4 @@ xdoctest.doctest\_example module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.doctest_part.rst → docs/source/auto/xdoctest.doctest_part.rst

@@ -5,3 +5,4 @@ xdoctest.doctest\_part module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.dynamic_analysis.rst → docs/source/auto/xdoctest.dynamic_analysis.rst

@@ -5,3 +5,4 @@ xdoctest.dynamic\_analysis module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.exceptions.rst → docs/source/auto/xdoctest.exceptions.rst

@@ -5,3 +5,4 @@ xdoctest.exceptions module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.global_state.rst → docs/source/auto/xdoctest.global_state.rst

@@ -5,3 +5,4 @@ xdoctest.global\_state module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.parser.rst → docs/source/auto/xdoctest.parser.rst

@@ -5,3 +5,4 @@ xdoctest.parser module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.plugin.rst → docs/source/auto/xdoctest.plugin.rst

@@ -5,3 +5,4 @@ xdoctest.plugin module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.rst → 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:

docs/source/xdoctest.runner.rst → docs/source/auto/xdoctest.runner.rst

@@ -5,3 +5,4 @@ xdoctest.runner module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.static_analysis.rst → docs/source/auto/xdoctest.static_analysis.rst

@@ -5,3 +5,4 @@ xdoctest.static\_analysis module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.utils.rst → docs/source/auto/xdoctest.utils.rst

@@ -23,3 +23,4 @@ Module contents
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.utils.util_deprecation.rst → docs/source/auto/xdoctest.utils.util_deprecation.rst

@@ -5,3 +5,4 @@ xdoctest.utils.util\_deprecation module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.utils.util_import.rst → docs/source/auto/xdoctest.utils.util_import.rst

@@ -5,3 +5,4 @@ xdoctest.utils.util\_import module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.utils.util_misc.rst → docs/source/auto/xdoctest.utils.util_misc.rst

@@ -5,3 +5,4 @@ xdoctest.utils.util\_misc module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.utils.util_mixins.rst → docs/source/auto/xdoctest.utils.util_mixins.rst

@@ -5,3 +5,4 @@ xdoctest.utils.util\_mixins module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.utils.util_notebook.rst → docs/source/auto/xdoctest.utils.util_notebook.rst

@@ -5,3 +5,4 @@ xdoctest.utils.util\_notebook module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.utils.util_path.rst → docs/source/auto/xdoctest.utils.util_path.rst

@@ -5,3 +5,4 @@ xdoctest.utils.util\_path module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.utils.util_str.rst → docs/source/auto/xdoctest.utils.util_str.rst

@@ -5,3 +5,4 @@ xdoctest.utils.util\_str module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

docs/source/xdoctest.utils.util_stream.rst → docs/source/auto/xdoctest.utils.util_stream.rst

@@ -5,3 +5,4 @@ xdoctest.utils.util\_stream module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:

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)

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

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<xdoctest.directive>`. For more information on
-directives see :doc:`the docs for the xdoctest directive
-module<xdoctest.directive>`.
+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<auto/xdoctest.directive>`.
 
 
 .. 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>`.
 '''
 
 

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

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

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