def test_nest_paths(self):
j = os.path.join
result = utils.nest_paths([
'index.md',
j('user-guide', 'configuration.md'),
j('user-guide', 'styling-your-docs.md'),
j('user-guide', 'writing-your-docs.md'),
j('about', 'contributing.md'),
j('about', 'license.md'),
j('about', 'release-notes.md'),
])
self.assertEqual(result, [
'index.md', {
'User guide': [
j('user-guide', 'configuration.md'),
j('user-guide', 'styling-your-docs.md'),
j('user-guide', 'writing-your-docs.md')
]
}, {
'About': [
j('about', 'contributing.md'),
j('about', 'license.md'),
j('about', 'release-notes.md')
]
}
])
def test_nest_paths(self):
j = os.path.join
result = utils.nest_paths([
'index.md',
j('user-guide', 'configuration.md'),
j('user-guide', 'styling-your-docs.md'),
j('user-guide', 'writing-your-docs.md'),
j('about', 'contributing.md'),
j('about', 'license.md'),
j('about', 'release-notes.md'),
])
self.assertEqual(
result,
[
'index.md',
{'User guide': [
j('user-guide', 'configuration.md'),
j('user-guide', 'styling-your-docs.md'),
j('user-guide', 'writing-your-docs.md')]},
{'About': [
j('about', 'contributing.md'),
j('about', 'license.md'),
j('about', 'release-notes.md')]}
]
)
def post_validation(self, config, key_name):
if config[key_name] is not None:
return
pages = []
for filename in self.walk_docs_dir(config['docs_dir']):
if os.path.splitext(filename)[0] == 'index':
pages.insert(0, filename)
else:
pages.append(filename)
config[key_name] = utils.nest_paths(pages)
def post_validation(self, config, key_name):
if config[key_name] is not None:
return
pages = []
for filename in self.walk_docs_dir(config['docs_dir']):
if os.path.splitext(filename)[0] == 'index':
pages.insert(0, filename)
else:
pages.append(filename)
config[key_name] = utils.nest_paths(pages)
def get_navigation(files, config):
""" Build site navigation from config and files."""
nav_config = config['nav'] or nest_paths(
f.src_path for f in files.documentation_pages())
items = _data_to_navigation(nav_config, files, config)
if not isinstance(items, list):
items = [items]
# Get only the pages from the navigation, ignoring any sections and links.
pages = _get_by_type(items, Page)
# Include next, previous and parent links.
_add_previous_and_next_links(pages)
_add_parent_links(items)
missing_from_config = [
file for file in files.documentation_pages() if file.page is None
]
if missing_from_config:
log.info(
'The following pages exist in the docs directory, but are not '
'included in the "nav" configuration:\n - {}'.format(
'\n - '.join([file.src_path
for file in missing_from_config])))
# Any documentation files not found in the nav should still have an associated page, so we
# create them here. The Page object will automatically be assigned to `file.page` during
# its creation (and this is the only way in which these page objects are accessable).
for file in missing_from_config:
Page(None, file, config)
links = _get_by_type(items, Link)
for link in links:
scheme, netloc, path, params, query, fragment = urlparse(link.url)
if scheme or netloc:
log.debug("An external link to '{}' is included in "
"the 'nav' configuration.".format(link.url))
elif link.url.startswith('/'):
log.debug(
"An absolute path to '{}' is included in the 'nav' configuration, "
"which presumably points to an external resource.".format(
link.url))
else:
msg = (
"A relative path to '{}' is included in the 'nav' configuration, "
"which is not found in the documentation files".format(
link.url))
log.warning(msg)
return Navigation(items, pages)
def get_navigation(files, config):
""" Build site navigation from config and files."""
nav_config = config['nav'] or nest_paths(f.src_path for f in files.documentation_pages())
items = _data_to_navigation(nav_config, files, config)
if not isinstance(items, list):
items = [items]
# Get only the pages from the navigation, ignoring any sections and links.
pages = _get_by_type(items, Page)
# Include next, previous and parent links.
_add_previous_and_next_links(pages)
_add_parent_links(items)
missing_from_config = [file for file in files.documentation_pages() if file.page is None]
if missing_from_config:
log.info(
'The following pages exist in the docs directory, but are not '
'included in the "nav" configuration:\n - {}'.format(
'\n - '.join([file.src_path for file in missing_from_config]))
)
# Any documentation files not found in the nav should still have an associated page.
# However, these page objects are only accessable from File instances as `file.page`.
for file in missing_from_config:
Page(None, file, config)
links = _get_by_type(items, Link)
for link in links:
scheme, netloc, path, params, query, fragment = urlparse(link.url)
if scheme or netloc:
log.debug(
"An external link to '{}' is included in "
"the 'nav' configuration.".format(link.url)
)
elif link.url.startswith('/'):
log.debug(
"An absolute path to '{}' is included in the 'nav' configuration, "
"which presumably points to an external resource.".format(link.url)
)
else:
msg = (
"A relative path to '{}' is included in the 'nav' configuration, "
"which is not found in the documentation files".format(link.url)
)
log.warning(msg)
return Navigation(items, pages)
def on_config(self, config):
# print(config)
self.files = {}
self.module_files = {}
for module_name, details in self.config["modules"].items():
target = details["section"]
self.module_files[target] = []
source_location = details["source_repo"]
source_location = os.path.expandvars(source_location)
module = importlib.import_module(module_name)
importlib.reload(module)
src_path = pathlib.Path(module.__file__).parent.parent.absolute()
target_path = pathlib.Path(config["site_dir"])
for module, file in get_submodule_files(module,
details.get("hidden", [])):
importlib.reload(module)
do_doc = functools.partial(
doc_module,
module.__name__,
module,
"",
source_location,
file.stem != "__init__.py",
)
f = PyDocFile(
target / file,
src_path,
target_path,
True,
pathlib.Path(module.__file__).absolute(),
)
# print(f.__dict__)
# print()
self.files[f.url] = (f, do_doc)
self.module_files[target].append(f)
if config["nav"]:
try:
ix, nav = find_section_anchor(config["nav"],
f"api-docs-{target}")
nav[ix] = nest_paths(f.src_path
for f in self.module_files[target])[0]
except ValueError:
pass
def get_navigation(files, config):
""" Build site navigation from config and files."""
nav_config = config['nav'] or nest_paths(f.src_path for f in files.documentation_pages())
items = _data_to_navigation(nav_config, files, config)
if not isinstance(items, list):
items = [items]
# Get only the pages from the navigation, ignoring any sections and links.
pages = _get_by_type(items, Page)
# Include next, previous and parent links.
_add_previous_and_next_links(pages)
_add_parent_links(items)
missing_from_config = [file for file in files.documentation_pages() if file.page is None]
if missing_from_config:
log.info(
'The following pages exist in the docs directory, but are not '
'included in the "nav" configuration:\n - {}'.format(
'\n - '.join([file.src_path for file in missing_from_config]))
)
# Any documentation files not found in the nav should still have an associated page.
# However, these page objects are only accessable from File instances as `file.page`.
for file in missing_from_config:
Page(None, file, config)
links = _get_by_type(items, Link)
if links:
# Assume all links are external.
# TODO: warn or error on internal links?
log.info(
'The following paths are included in the "nav" configuration, '
'but do not exist in the docs directory:\n - {}'.format(
'\n - '.join([link.url for link in links]))
)
return Navigation(items, pages)
