Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 17921cd

Browse files
astrofrogastrofrog
committed
Added extensive tests of running sphinx with different cases, and including reference output files that can be compared with the input files.
1 parent 496e818 commit 17921cd

29 files changed

+266
-1
lines changed

‎docs/automodsumm.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ the bulk of the work in creating the API tables and pages is done by
1616
Nevertheless, in most cases, users should not need to call ``automodsumm``
1717
directly, except if finer control is desired. The syntax of the directive is::
1818

19-
.. aautomodsumm:: mypackage.mymodule
19+
.. automodsumm:: mypackage.mymodule
2020
<options go here>
2121

2222
.. TODO: the typo above is deliberate, to avoid the directive getting picked

‎sphinx_automodapi/tests/cases/func_headings/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
A simple case where we are only looking at a module with functions, so no issues with inherited classes etc

‎sphinx_automodapi/tests/cases/func_headings/input/index.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.. automodapi:: sphinx_automodapi.tests.example_module.functions
2+
:headings: *&^

‎sphinx_automodapi/tests/cases/func_headings/output/api/sphinx_automodapi.tests.example_module.functions.add.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
2+
3+
add
4+
====================================================
5+
6+
.. currentmodule:: sphinx_automodapi.tests.example_module.functions
7+
8+
.. autofunction:: add

‎sphinx_automodapi/tests/cases/func_headings/output/api/sphinx_automodapi.tests.example_module.functions.multiply.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
2+
3+
multiply
4+
=========================================================
5+
6+
.. currentmodule:: sphinx_automodapi.tests.example_module.functions
7+
8+
.. autofunction:: multiply

‎sphinx_automodapi/tests/cases/func_headings/output/index.rst.automodapi

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
2+
sphinx_automodapi.tests.example_module.functions Module
3+
*******************************************************
4+
5+
.. automodule:: sphinx_automodapi.tests.example_module.functions
6+
7+
Functions
8+
&&&&&&&&&
9+
10+
.. automodsumm:: sphinx_automodapi.tests.example_module.functions
11+
:functions-only:
12+
:toctree: api/

‎sphinx_automodapi/tests/cases/func_headings/output/index.rst.automodsumm

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
.. currentmodule:: sphinx_automodapi.tests.example_module.functions
2+
3+
.. autosummary::
4+
:toctree: api/
5+
6+
add
7+
multiply
8+

‎sphinx_automodapi/tests/cases/func_noheading/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
A simple case where we are only looking at a module with functions, so no issues with inherited classes etc

‎sphinx_automodapi/tests/cases/func_noheading/input/index.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.. automodapi:: sphinx_automodapi.tests.example_module.functions
2+
:no-heading:

‎sphinx_automodapi/tests/cases/func_noheading/output/api/sphinx_automodapi.tests.example_module.functions.add.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
2+
3+
add
4+
====================================================
5+
6+
.. currentmodule:: sphinx_automodapi.tests.example_module.functions
7+
8+
.. autofunction:: add

‎sphinx_automodapi/tests/cases/func_noheading/output/api/sphinx_automodapi.tests.example_module.functions.multiply.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
2+
3+
multiply
4+
=========================================================
5+
6+
.. currentmodule:: sphinx_automodapi.tests.example_module.functions
7+
8+
.. autofunction:: multiply

‎sphinx_automodapi/tests/cases/func_noheading/output/index.rst.automodapi

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
.. automodule:: sphinx_automodapi.tests.example_module.functions
2+
3+
Functions
4+
^^^^^^^^^
5+
6+
.. automodsumm:: sphinx_automodapi.tests.example_module.functions
7+
:functions-only:
8+
:toctree: api/

‎sphinx_automodapi/tests/cases/func_noheading/output/index.rst.automodsumm

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
.. currentmodule:: sphinx_automodapi.tests.example_module.functions
2+
3+
.. autosummary::
4+
:toctree: api/
5+
6+
add
7+
multiply
8+

‎sphinx_automodapi/tests/cases/func_nomaindocstring/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
A simple case where we are only looking at a module with functions, so no issues with inherited classes etc

‎sphinx_automodapi/tests/cases/func_nomaindocstring/input/index.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.. automodapi:: sphinx_automodapi.tests.example_module.functions
2+
:no-main-docstr:

‎sphinx_automodapi/tests/cases/func_nomaindocstring/output/api/sphinx_automodapi.tests.example_module.functions.add.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
2+
3+
add
4+
====================================================
5+
6+
.. currentmodule:: sphinx_automodapi.tests.example_module.functions
7+
8+
.. autofunction:: add

‎sphinx_automodapi/tests/cases/func_nomaindocstring/output/api/sphinx_automodapi.tests.example_module.functions.multiply.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
2+
3+
multiply
4+
=========================================================
5+
6+
.. currentmodule:: sphinx_automodapi.tests.example_module.functions
7+
8+
.. autofunction:: multiply

‎sphinx_automodapi/tests/cases/func_nomaindocstring/output/index.rst.automodapi

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
2+
sphinx_automodapi.tests.example_module.functions Module
3+
-------------------------------------------------------
4+
5+
6+
7+
Functions
8+
^^^^^^^^^
9+
10+
.. automodsumm:: sphinx_automodapi.tests.example_module.functions
11+
:functions-only:
12+
:toctree: api/

‎sphinx_automodapi/tests/cases/func_nomaindocstring/output/index.rst.automodsumm

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
.. currentmodule:: sphinx_automodapi.tests.example_module.functions
2+
3+
.. autosummary::
4+
:toctree: api/
5+
6+
add
7+
multiply
8+

‎sphinx_automodapi/tests/cases/func_simple/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
A simple case where we are only looking at a module with functions, so no issues with inherited classes etc

‎sphinx_automodapi/tests/cases/func_simple/input/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.. automodapi:: sphinx_automodapi.tests.example_module.functions

‎sphinx_automodapi/tests/cases/func_simple/output/api/sphinx_automodapi.tests.example_module.functions.add.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
2+
3+
add
4+
====================================================
5+
6+
.. currentmodule:: sphinx_automodapi.tests.example_module.functions
7+
8+
.. autofunction:: add

‎sphinx_automodapi/tests/cases/func_simple/output/api/sphinx_automodapi.tests.example_module.functions.multiply.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
2+
3+
multiply
4+
=========================================================
5+
6+
.. currentmodule:: sphinx_automodapi.tests.example_module.functions
7+
8+
.. autofunction:: multiply

‎sphinx_automodapi/tests/cases/func_simple/output/index.rst.automodapi

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
2+
sphinx_automodapi.tests.example_module.functions Module
3+
-------------------------------------------------------
4+
5+
.. automodule:: sphinx_automodapi.tests.example_module.functions
6+
7+
Functions
8+
^^^^^^^^^
9+
10+
.. automodsumm:: sphinx_automodapi.tests.example_module.functions
11+
:functions-only:
12+
:toctree: api/

‎sphinx_automodapi/tests/cases/func_simple/output/index.rst.automodsumm

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
.. currentmodule:: sphinx_automodapi.tests.example_module.functions
2+
3+
.. autosummary::
4+
:toctree: api/
5+
6+
add
7+
multiply
8+

‎sphinx_automodapi/tests/example_module/__init__.py

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
from .classes import *
2+
from .functions import *

‎sphinx_automodapi/tests/example_module/classes.py

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
__all__ = ['Spam']
2+
3+
4+
class BaseSpam(object):
5+
"""
6+
Base class for Spam
7+
"""
8+
9+
def eat(self, time):
10+
"""
11+
Eat some spam in the required time.
12+
"""
13+
pass
14+
15+
def buy(self, price):
16+
"""
17+
Buy some MOAR spam.
18+
"""
19+
pass
20+
21+
22+
class Spam(BaseSpam):
23+
"""
24+
The main spam
25+
"""
26+
pass

‎sphinx_automodapi/tests/example_module/functions.py

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
"""
2+
A collection of useful functions
3+
"""
4+
5+
__all__ = ['add', 'multiply']
6+
7+
8+
def add(a, b):
9+
"""
10+
Add two numbers
11+
"""
12+
return a + b
13+
14+
15+
def multiply(c, d):
16+
"""
17+
Multiply two numbers
18+
"""
19+
return c * d

‎sphinx_automodapi/tests/test_cases.py

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# The following tests use a plain Python example module that is at
2+
# sphinx_automodapi.tests.example_module.
3+
4+
# We store different cases in the cases sub-directory of the tests directory
5+
6+
import os
7+
import glob
8+
import shutil
9+
import pytest
10+
from copy import deepcopy
11+
from sphinx import build_main
12+
13+
CASES_ROOT = os.path.join(os.path.dirname(__file__), 'cases')
14+
15+
CASES_DIRS = glob.glob(os.path.join(CASES_ROOT, '*'))
16+
17+
18+
def write_conf(filename, conf):
19+
with open(filename, 'w') as f:
20+
for key, value in conf.items():
21+
f.write("{0} = {1}\n".format(key, repr(conf[key])))
22+
23+
24+
DEFAULT_CONF = {'source_suffix': '.rst',
25+
'master_doc': 'index',
26+
'nitpicky': True,
27+
'extensions': ['sphinx_automodapi.automodapi']}
28+
29+
30+
@pytest.mark.parametrize('case_dir', CASES_DIRS)
31+
def test_run_full_case(tmpdir, case_dir):
32+
33+
input_dir = os.path.join(case_dir, 'input')
34+
output_dir = os.path.join(case_dir, 'output')
35+
36+
src_dir = tmpdir.mkdir('src').strpath
37+
38+
conf = deepcopy(DEFAULT_CONF)
39+
conf.update({'automodapi_toctreedirnm': 'api',
40+
'automodapi_writereprocessed': True,
41+
'automodsumm_writereprocessed': True})
42+
43+
write_conf(os.path.join(src_dir, 'conf.py'), conf)
44+
45+
for input_file in glob.glob(os.path.join(input_dir, '*')):
46+
shutil.copy(input_file, os.path.join(src_dir, os.path.basename(input_file)))
47+
48+
start_dir = os.path.abspath('.')
49+
50+
try:
51+
os.chdir(src_dir)
52+
build_main(argv=('sphinx-build', '-b', 'html', '.', 'build/_html'))
53+
finally:
54+
os.chdir(start_dir)
55+
56+
# Check that all expected output files are there and match the reference files
57+
for root, dirnames, filenames in os.walk(output_dir):
58+
for filename in filenames:
59+
path_reference = os.path.join(root, filename)
60+
path_relative = os.path.relpath(path_reference, output_dir)
61+
path_actual = os.path.join(src_dir, path_relative)
62+
assert os.path.exists(path_actual)
63+
actual = open(path_actual).read()
64+
reference = open(path_reference).read()
65+
assert actual.strip() == reference.strip()
66+
# if actual != reference:
67+
# raise ValueError("Expected:\n\n{0}\n\nGot:\n\n{1}\n".format(reference, actual))

0 commit comments

Comments
 (0)