def create_external_configs(namespace):
# type: (argparse.Namespace) -> None
"""
Create `GitHub Pages` and `Read the Docs` configuration files.
"""
logger = get_logger()
configs = (
("gh_pages_config.yml", namespace.output_path / "_config.yml"),
("mkdocs.yml", namespace.input_path / "mkdocs.yml"),
("readthedocs.yml", namespace.input_path / ".readthedocs.yml"),
)
for asset_name, target_path in configs:
if target_path.exists():
continue
logger.info("Creating {} file".format(target_path))
render_asset(
asset_name,
target_path,
dict(
source_code_url=namespace.source_code_url.replace(
"blob/master/", ""),
project_name=make_title(namespace.input_path.name),
docs_path=PathFinder(namespace.input_path).relative(
namespace.output_path).as_posix(),
),
)
def _build_modules_toc_lines(self, import_string, max_depth, md_document,
start_level):
# type: (ImportString, int, MDDocument, int) -> List[Text]
lines = [] # type: List[Text]
parts = import_string.parts
last_import_string_parts = [] # type: List[Text]
for module_record in self._module_records:
output_path = self._loader.get_output_path(
module_record.source_path)
if module_record.import_string == import_string:
continue
if import_string and not module_record.import_string.startswith(
import_string):
continue
import_string_parts = module_record.import_string.parts
if len(import_string_parts) > len(parts) + max_depth:
continue
for index, import_string_part in enumerate(
import_string_parts[:-1]):
if index < len(parts):
continue
if (len(last_import_string_parts) > index
and last_import_string_parts[index]
== import_string_parts[index]):
continue
title = make_title(import_string_part)
toc_line = md_document.get_toc_line(title,
level=index - len(parts) +
start_level)
lines.append(toc_line)
last_import_string_parts = import_string_parts
link = md_document.render_doc_link(
title=module_record.title,
target_path=output_path,
anchor=md_document.get_anchor(module_record.title),
)
toc_line = md_document.get_toc_line(
link,
level=len(import_string_parts) - len(parts) - 1 + start_level)
lines.append(toc_line)
return lines
def __init__(
self,
input_path, # type: Path
output_path, # type: Path
source_paths, # type: Iterable[Path]
project_name=None, # type: Optional[Text]
docstring_processor=None, # type: Optional[BaseDocstringProcessor]
loader=None, # type: Optional[Loader]
raise_errors=False, # type: bool
source_code_url=None, # type: Optional[Text]
toc_depth=1, # type: int
):
# type: (...) -> None
self._logger = get_logger()
self._root_path = input_path
self._output_path = output_path
self._project_name = project_name or make_title(input_path.name)
self._root_path_finder = PathFinder(self._root_path)
self._source_code_url = source_code_url
self._toc_depth = toc_depth
self._raise_errors = raise_errors
# create output folder if it does not exist
if not self._output_path.exists():
self._logger.info("Creating folder {}".format(self._output_path))
PathFinder(self._output_path).mkdir()
self._loader = loader or Loader(root_path=self._root_path,
output_path=self._output_path)
self._docstring_processor = docstring_processor or SmartDocstringProcessor(
)
self._source_paths = sorted(source_paths)
self._error_output_paths = set() # type: Set[Path]
self._logger.debug("Generating source map for {} source files".format(
len(self._source_paths)))
self._module_records = self._build_module_record_list()
self._logger.debug("Source map generated")
package_names = self._module_records.get_package_names()
package_names_re_expr = "|".join(package_names)
self._docstring_links_re = re.compile(
r"`+(?:{})\.\S+`+".format(package_names_re_expr))
self._prepare_index()
def _build_module_record_list(self):
# type: () -> ModuleRecordList
module_record_list = ModuleRecordList()
for source_path in self._source_paths:
module_record = None
try:
module_record = self._loader.get_module_record(source_path)
except LoaderError as e:
if self._raise_errors:
raise
self._logger.warning("Skipping: {}".format(e))
continue
if module_record:
# if not module_record.title:
# the title was somehow being set in pascal case
module_record.title = make_title(module_record.name)
module_record_list.add(module_record)
return module_record_list
def _build_breadcrumbs_string(self, module_record, md_document):
# type: (ModuleRecord, MDDocument) -> Text
import_string_breadcrumbs = [] # type: List[Text]
parent_import_strings = []
import_string = module_record.import_string
while not import_string.is_top_level():
import_string = import_string.parent
parent_import_strings.append(import_string)
parent_import_strings.reverse()
for parent_import_string in parent_import_strings:
parent_module_record = self._module_records.find_module_record(
parent_import_string)
if not parent_module_record:
import_string_breadcrumbs.append("`{}`".format(
make_title(parent_import_string.parts[-1])))
continue
output_path = self._loader.get_output_path(
parent_module_record.source_path)
import_string_breadcrumbs.append(
md_document.render_doc_link(
parent_module_record.title,
target_path=output_path,
anchor=md_document.get_anchor(parent_module_record.title),
))
breadcrumbs = ([
md_document.render_md_doc_link(self.md_index,
title=self._project_name),
md_document.render_md_doc_link(self.md_modules,
title=self.MODULES_TITLE),
] + import_string_breadcrumbs + [module_record.title])
return " / ".join(breadcrumbs)
def test_make_title(self):
self.assertEqual(make_title("my_path.py"), "My Path Py")
self.assertEqual(make_title("my_title"), "My Title")
self.assertEqual(make_title("__init__.py"), "Init Py")
self.assertEqual(make_title("__main__"), "Module")