def setup_docs(
path: Union[str, Path],
config: DictConfig,
ledger: Ledger,
overwrite: bool = False,
) -> None:
"""
Configure the project documentation.
When calling this function, it generates a documentation folder that
contains necessary configuration files (requirement lists, 'make' commands,
sphinx configurations) for building the documentation of the project.
Args:
path: Target folder where the generated files will be written.
config: DictConfig containing the selected project configuration.
ledger: Ledger object. Keeps track of the generated files.
overwrite: If True, overwrites existing files. Otherwise files
that already exists will not be modified.
"""
if not config.project.get("docs", False):
return
create_docs_directories(root_path=path)
source_files = {"conf.txt", "index.md"}
docs_path = Path(path) / "docs"
for file in DOCS_FILES:
out_path = (docs_path /
"source") if file.name in source_files else docs_path
write_template(file,
config=config,
path=out_path,
ledger=ledger,
overwrite=overwrite)
def dump_ledger(
path: Union[str, Path],
config: DictConfig,
ledger: Ledger,
overwrite: bool = False,
) -> None:
"""
Write the summary of the generated files.
This method collects the elements stored in ledger to create a markdown
document that summarizes all the files generated by the MLOQ application.
Args:
path: Target folder where the generated files will be written.
config: DictConfig containing the selected project configuration.
ledger: Ledger object. Keeps track of the generated files.
overwrite: If True, overwrites existing files. Otherwise files
that already exists will not be modified.
"""
config.template = DictConfig({
**config.template, "generated_files":
ledger.files
})
write_template(
what_mloq_generated,
config=config,
path=path,
ledger=ledger,
overwrite=overwrite,
)
def create_project_skeleton(
root_path: Path,
config: DictConfig,
ledger: Ledger,
overwrite: bool = False,
) -> None:
"""
Initialize the folder structure of a new Python project together with a bare minimum set of \
code files.
It creates a directory for the project containing an empty __init__.py file, and a \
tests folder inside it with its corresponding __init__.py file. This function will only \
create new files and folders in case they don't already exist, but it won't overwrite any \
existing file.
Args:
root_path: Absolute path where the new project folder will be created.
config: Contains all the parameters that define how the project will be set up.
ledger: Book keeper for the generated files.
overwrite: If False, copy the file if it does not already exists in the \
target path. If True, overwrite the target file if it is already present.
Returns:
None.
"""
project_name = config.template.project_name
# Project dir
try:
project_path = root_path / project_name
os.makedirs(project_path, exist_ok=True)
description = "Python package header for the project module"
copy_file(init,
project_path,
ledger,
overwrite,
description=description)
copy_file(version, project_path, ledger, overwrite)
write_template(main,
config=config,
path=project_path,
ledger=ledger,
overwrite=overwrite)
# Test dir inside project
test_path = project_path / "tests"
os.makedirs(test_path, exist_ok=True)
write_template(
test_main,
config=config,
path=test_path,
ledger=ledger,
overwrite=overwrite,
)
description = "Python package header for the test module"
copy_file(init, test_path, ledger, overwrite, description=description)
except (PermissionError, FileNotFoundError) as e:
raise Failure() from e
def setup_workflows(workflows, root_path: Path, params, override: bool = False):
"""Add the target workflows to the corresponding .github/workflows repository."""
create_github_actions_directories(root_path)
workflows_path = root_path / ".github" / "workflows"
# TODO: Check for incompatible workflows
for wkflow_name in workflows:
workflow = WORKFLOW_NAMES.get(wkflow_name)
if workflow is None:
print(f"Workflow {wkflow_name} not defined. Skipping")
else:
write_template(workflow, params, workflows_path, override)
def init_repository(path,
config_file: Optional[Union[Path, str]] = None,
override: bool = False):
"""Initialize the project folder structure and all the filled in boilerplate files."""
config_file = path / "repository.yaml" if config_file is None else config_file
config = read_config(config_file)
template = config["template"]
create_github_actions_directories(path)
create_project_directories(project_name=template["project_name"],
root_path=path,
override=override)
for file in ROOT_PATH_FILES:
write_template(file,
params=template,
target_path=path,
override=override)
if "workflows" in config:
setup_workflows(config["workflows"],
root_path=path,
params=template,
override=override)
def setup_workflow_template(
root_path: Union[Path, str],
config: DictConfig,
ledger: Ledger,
overwrite: bool = False,
):
"""Add the target workflows to the corresponding .github/workflows repository."""
workflow = config.project.get("ci", "empty")
if is_empty(workflow):
return
root_path = Path(root_path)
create_github_actions_directories(root_path)
workflows_path = Path(root_path) / ".github" / "workflows"
workflow_file = WORKFLOW_NAMES.get(workflow)
if workflow_file is None:
_logger.warning(f"Workflow {workflow} not defined. Skipping")
else:
write_template(
workflow_file,
config=config,
path=workflows_path,
ledger=ledger,
overwrite=overwrite,
)
def setup_root_files(
path: Union[str, Path],
config: DictConfig,
ledger: Ledger,
overwrite: bool = False,
) -> None:
"""
Initialize root folder files.
It writes repository files using as input the incoming DictConfig,
which summarizes the options chosen by the user.
Args:
path: Target folder where the generated files will be written.
config: DictConfig containing the selected project configuration.
ledger: Ledger object. Keeps track of the generated files.
overwrite: If True, overwrites existing files. Otherwise files
that already exists will not be modified.
"""
for file in ROOT_PATH_FILES:
write_template(file,
config=config,
path=path,
ledger=ledger,
overwrite=overwrite)
if config.project.get("docker"):
write_template(dockerfile,
config=config,
path=path,
ledger=ledger,
overwrite=overwrite)
if config.project.get("mlflow"):
write_template(mlproject,
config=config,
path=path,
ledger=ledger,
overwrite=overwrite)
if config.project.get("open_source"):
for file in OPEN_SOURCE_FILES:
write_template(file,
config=config,
path=path,
ledger=ledger,
overwrite=overwrite)
license = config.template.license
write_template(
LICENSES[license],
config=config,
path=path,
ledger=ledger,
overwrite=overwrite,
)
else:
license = "proprietary"
license_classifiers = {
"MIT": "License :: OSI Approved :: MIT License",
"Apache-2.0": "License :: OSI Approved :: Apache Software License",
"GPL-3.0":
"License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
"proprietary": "License :: Other/Proprietary License",
}
license_classifer = license_classifiers[license]
config = DictConfig({**config, "license_classifier": license_classifer})
write_template(setup_py,
config=config,
path=path,
ledger=ledger,
overwrite=overwrite)