def index(input_path):
"""
Create the content of an index page, listing all files in the given path.
Sub folders are not visited.
Args:
input_path(string): the path where all files to convert are located.
Returns:
string: the index page content.
"""
content = make_title(os.path.basename(input_path), 0)
content += INDEX_HEADER
processed_files = []
for file_name in sorted(os.listdir(input_path)):
if file_name.endswith(YML_EXTENSION) or \
file_name.endswith(JSON_EXTENSION):
# remove the extension
abs_name = change_extension(file_name, '')
if abs_name not in processed_files:
content += NL + TAB + change_extension(file_name, '')
processed_files.append(abs_name)
return content
def create_master_index(root_path):
"""
Create the main index containing inner indexes. It searches for every
``index.rst`` in all sub folders and add it to its toctree. The list of
all indexes files found is written in a new
``index.rst``
Args:
root_path(string): the starting path from which recursively searches
indexes.
"""
content = make_title(MASTER_INDEX_TITLE, 0)
content += INDEX_HEADER + NL
files = os.walk(root_path)
for input_file in files:
root, dirs, files = input_file
rel_path = os.path.relpath(root, root_path)
files.sort()
for name in files:
if "__pycache__" in rel_path:
continue
if (rel_path == ".") ^ (name == INDEX_FILE_NAME):
content += TAB \
+ os.path.join(rel_path, change_extension(name, '')) \
+ NL2
write_index_file(root_path, content)
def schema2rst(schema_file, excluded_key):
"""
Parse a json/yaml schema file into RST text.
Example:
with open("schema.json") as schema:
print(jsonschema2rst(schema))
Args:
schema_file(file): a json or yaml schema file descriptor.
excluded_key(string): csv containing schema's keywords to ignore
Returns:
string: a restructured-text string representing ``schema_file``
"""
tree = TreeNode(
os.path.basename(change_extension(schema_file.name, JSON_EXTENSION)))
rst = RST_DIRECTIVES
TreeNode.dict2tree(yaml.load(schema_file), tree, excluded_key)
rst += _traverse_bfs(tree, _node2rst)
return rst
def run_parser(
input_path,
output_path,
excluded_key="uniqueItems,additionalProperties,$schema",
yaml_only=False,
):
"""
This function copies the needed resources into the ``output_path``,
runs the ``jsonschema2rst`` recursively on ``input_path`` parsing all yaml
schemas, and create an index listing and linking all those files.
Args:
input_path(string): the folder where yaml schemas are located.
output_path(string): the folder where all resources and
restructured-text generated files will be placed. Note that,
if the folder already exists, it is deleted, otherwise a new one
is created.
excluded_key(string): csv containing schema's keywords to ignore
Raises:
OSError: if ``output_path``is not accessible (Permission denied)
"""
if not os.path.exists(input_path):
raise IOError('Wrong path: {}. Program will exit'.format(input_path))
output_path = os.path.abspath(output_path)
input_files = os.walk(input_path)
processed_files = []
for input_file in input_files:
root, dirs, files = input_file
# create, if not exists, the sub folder where rst file will be written
output_folder = _get_output_folder(output_path, input_path, root)
if not os.path.exists(output_folder):
os.makedirs(output_folder)
# write it on the FS this sub-folder content's index
index_content = index(root)
write_index_file(output_folder, index_content)
for name in files:
if (name.endswith(YML_EXTENSION)
or (not yaml_only and name.endswith(JSON_EXTENSION))):
# check if a file with same name has been already parsed
abs_name = change_extension(name, '')
if abs_name in processed_files:
continue
file_name = os.path.join(root, name)
with open(file_name) as schema:
rst_content = schema2rst(schema, excluded_key)
output = os.path.join(output_folder, _get_rst_name(name))
with open(output, 'wb') as rst_out:
rst_out.write(rst_content.encode('utf-8'))
processed_files.append(abs_name)
print(abs_name.ljust(40) + 'OK')
create_master_index(output_path)
print('Index created.\n')
def _get_rst_name(name):
return change_extension(name, RST_EXTENSION)
def test_change_extension_no_ext():
expected = 'foobar.txt'
result = change_extension('foobar', '.txt')
assert result == expected
def test_change_extension_remove_ext():
expected = 'foobar'
result = change_extension('foobar.txt', '')
assert result == expected
def test_change_extension_harder():
expected = 'foobar.yml.yml'
result = change_extension('foobar.yml.json', '.yml')
assert result == expected