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 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)