Skip to content
This repository was archived by the owner on Feb 2, 2024. It is now read-only.

Commit e6522b7

Browse files
densmirndensmirn
authored
Add generating of examples list (#768)
1 parent 1f64362 commit e6522b7

File tree

4 files changed

+187
-8
lines changed

4 files changed

+187
-8
lines changed

‎docs/source/buildscripts/examples_generator.py‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# -*- coding: utf-8 -*-
2+
# *****************************************************************************
3+
# Copyright (c) 2020, Intel Corporation All rights reserved.
4+
#
5+
# Redistribution and use in source and binary forms, with or without
6+
# modification, are permitted provided that the following conditions are met:
7+
#
8+
# Redistributions of source code must retain the above copyright notice,
9+
# this list of conditions and the following disclaimer.
10+
#
11+
# Redistributions in binary form must reproduce the above copyright notice,
12+
# this list of conditions and the following disclaimer in the documentation
13+
# and/or other materials provided with the distribution.
14+
#
15+
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
16+
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
17+
# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
18+
# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
19+
# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
20+
# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21+
# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
22+
# OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
23+
# WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
24+
# OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
25+
# EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26+
# *****************************************************************************
27+
from pathlib import Path
28+
29+
from sdc_object_utils import get_sdc_object_by_pandas_name, init_sdc_structure
30+
from sdc_doc_utils import get_docstring, reindent, split_in_sections
31+
from apiref_generator import (APIREF_TEMPLATE_FNAMES, reformat)
32+
33+
34+
EXAMPLES_REL_PATH = Path('.') / '_examples'
35+
36+
37+
def get_obj_examples(pandas_name):
38+
"""
39+
Get list of examples for Pandas object.
40+
41+
:param pandas_name: Pandas object for which documentation to be generated.
42+
:return: Generated docstring.
43+
"""
44+
sdc_obj = get_sdc_object_by_pandas_name(pandas_name)
45+
sdc_doc = get_docstring(sdc_obj)
46+
sections = split_in_sections(reindent(sdc_doc, 0))
47+
sections_as_dict = {title.strip(): text for title, text in sections}
48+
example_section = sections_as_dict.get('Examples')
49+
if not example_section:
50+
return None
51+
52+
examples = []
53+
section_names = ['literalinclude', 'command-output']
54+
for subsection in example_section.strip().split('\n\n'):
55+
subsection = subsection.strip()
56+
if any(subsection.startswith(f'.. {name}') for name in section_names):
57+
# remove a directory level from path to examples
58+
examples.append(subsection.replace(' ../', ' '))
59+
60+
return reformat('\n\n'.join(examples))
61+
62+
63+
def get_tmpl_examples(fname_templ):
64+
"""Get all examples based on input template rst file"""
65+
tmpl_examples = []
66+
with open(fname_templ, encoding='utf-8') as fin:
67+
doc = fin.readlines()
68+
69+
while len(doc) > 0:
70+
# Parsing lines until ``.. sdc_toctree`` section is met
71+
while len(doc) > 0 and not doc[0].startswith('.. sdc_toctree'):
72+
line = doc[0]
73+
if line.startswith('.. currentmodule::'):
74+
current_module_name = line[19:].strip()
75+
doc.pop(0)
76+
77+
if len(doc) == 0:
78+
break
79+
80+
doc.pop(0) # Skipping ``.. sdc_toctree``
81+
82+
# Parsing the list of APIs
83+
while len(doc) > 0 and doc[0].strip() != '':
84+
line = doc[0]
85+
line = line.strip()
86+
full_name = current_module_name + '.' + line
87+
doc.pop(0)
88+
89+
obj_examples = get_obj_examples(full_name)
90+
if obj_examples:
91+
tmpl_examples.append(obj_examples)
92+
93+
if len(doc) == 0:
94+
break
95+
96+
return tmpl_examples
97+
98+
99+
def generate_examples():
100+
"""
101+
Master function for examples list generation.
102+
103+
This function initializes SDC data structures, and parses required templates for
104+
Final RST file generation that lists all the examples.
105+
"""
106+
init_sdc_structure()
107+
108+
all_examples = []
109+
for templ_fname in APIREF_TEMPLATE_FNAMES:
110+
all_examples += get_tmpl_examples(templ_fname)
111+
112+
if not EXAMPLES_REL_PATH.exists():
113+
EXAMPLES_REL_PATH.mkdir(parents=True, exist_ok=True)
114+
115+
examples_rst_path = EXAMPLES_REL_PATH / 'examples.rst'
116+
with examples_rst_path.open('w', encoding='utf-8') as fd:
117+
for examples in all_examples:
118+
fd.write(examples + '\n')
119+
120+
121+
if __name__ == "__main__":
122+
generate_examples()

‎docs/source/conf.py‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,33 @@
7373

7474
generate_api_reference()
7575

76+
SDC_DOC_NO_EXAMPLES_STR = 'SDC_DOC_NO_EXAMPLES'
77+
SDC_DOC_EXAMPLES_DIR = '_examples'
78+
79+
sdc_doc_no_examples = False # Generate examples list by default
80+
if SDC_DOC_NO_EXAMPLES_STR in os.environ:
81+
sdc_doc_no_examples = os.environ[SDC_DOC_NO_EXAMPLES_STR] == '1'
82+
83+
if not sdc_doc_no_examples:
84+
if os.path.exists(SDC_DOC_EXAMPLES_DIR):
85+
shutil.rmtree(SDC_DOC_EXAMPLES_DIR)
86+
87+
try:
88+
import sdc
89+
except ImportError:
90+
raise ImportError('Cannot import sdc.\n'
91+
'Documentation generator for Examples for a given module expects that module '
92+
'to be installed. Use conda/pip install SDC to install it prior to using API Examples '
93+
'generation. If you want to disable Examples generation, set the environment '
94+
'variable SDC_DOC_NO_EXAMPLES_STR=1')
95+
96+
try:
97+
from examples_generator import generate_examples
98+
except ImportError:
99+
raise ImportError('Cannot import examples_generator', os.getcwd())
100+
101+
generate_examples()
102+
76103
# -- Project information -----------------------------------------------------
77104

78105
project = 'Intel® Scalable Dataframe Compiler'

‎docs/source/examples.rst‎

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,34 @@
44
List of examples
55
================
66

7-
.. todo::
8-
Auto-generate the list of examples from respective docstrings in examples
7+
.. literalinclude:: ../../examples/basic_workflow.py
8+
:language: python
9+
:lines: 27-
10+
:caption: Basic workflow.
11+
:name: ex_basic_workflow
12+
13+
.. command-output:: python ./basic_workflow.py
14+
:cwd: ../../examples
15+
16+
17+
.. literalinclude:: ../../examples/basic_workflow_batch.py
18+
:language: python
19+
:lines: 27-
20+
:caption: Expanded basic workflow.
21+
:name: ex_basic_workflow_batch
22+
23+
.. command-output:: python ./basic_workflow_batch.py
24+
:cwd: ../../examples
25+
26+
27+
.. literalinclude:: ../../examples/basic_workflow_parallel.py
28+
:language: python
29+
:lines: 27-
30+
:caption: Basic workflow in parallel.
31+
:name: ex_basic_workflow_parallel
32+
33+
.. command-output:: python ./basic_workflow_parallel.py
34+
:cwd: ../../examples
35+
36+
37+
.. include:: _examples/examples.rst

‎sdc/datatypes/hpat_pandas_stringmethods_functions.py‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1022,12 +1022,13 @@ def hpat_pandas_stringmethods_strip(self, to_strip=None):
10221022
"""
10231023

10241024
seealso_strip_methods = """
1025-
:ref:`Series.str.strip <pandas.Series.str.strip>`
1026-
Remove leading and trailing characters in Series/Index.
1027-
:ref:`Series.str.lstrip <pandas.Series.str.lstrip>`
1028-
Remove leading characters in Series/Index.
1029-
:ref:`Series.str.strip <pandas.Series.str.strip>`
1030-
Remove trailing characters in Series/Index.
1025+
.. seealso::
1026+
:ref:`Series.str.strip <pandas.Series.str.strip>`
1027+
Remove leading and trailing characters in Series.
1028+
:ref:`Series.str.lstrip <pandas.Series.str.lstrip>`
1029+
Remove leading characters in Series.
1030+
:ref:`Series.str.strip <pandas.Series.str.strip>`
1031+
Remove trailing characters in Series.
10311032
"""
10321033

10331034

0 commit comments

Comments
 (0)