diff --git a/README.md b/README.md index 2d921b1..a80a712 100644 --- a/README.md +++ b/README.md @@ -95,6 +95,13 @@ How to do that, and how to handle some other special cases will follow. #### Using a `rosdoc2.yaml` file to control how your package is documented +To generate a default config file, run + +``` +$ rosdoc2 default_config \ + --package-path ./src/path/to/my_package_name +``` + TODO #### Packages with C/C++ API Documentation diff --git a/rosdoc2/verbs/default_config/__init__.py b/rosdoc2/verbs/default_config/__init__.py new file mode 100644 index 0000000..a665f36 --- /dev/null +++ b/rosdoc2/verbs/default_config/__init__.py @@ -0,0 +1,29 @@ +# Copyright 2024 Jonas Otto +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from .impl import main +from .impl import prepare_arguments + +__all__ = [ + 'entry_point_data', +] + +entry_point_data = { + 'verb': 'default_config', + 'description': 'Create a default rosdoc2 config file in a package', + # Called for execution, given parsed arguments object + 'main': main, + # Called first to setup argparse, given argparse parser + 'prepare_arguments': prepare_arguments, +} diff --git a/rosdoc2/verbs/default_config/impl.py b/rosdoc2/verbs/default_config/impl.py new file mode 100644 index 0000000..b31bc77 --- /dev/null +++ b/rosdoc2/verbs/default_config/impl.py @@ -0,0 +1,48 @@ +# Copyright 2024 Jonas Otto +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import os + +from ..build.create_format_map_from_package import create_format_map_from_package +from ..build.impl import get_package +from ..build.inspect_package_for_settings import DEFAULT_ROSDOC_CONFIG_FILE + + +def prepare_arguments(parser): + """Add command-line arguments to the argparse object.""" + parser.add_argument( + '--package-path', + '-p', + required=True, + help='path to the ROS package', + ) + return parser + + +def main(options): + """Execute command to create default config file.""" + package = get_package(options.package_path) + path = os.path.join(os.path.dirname(package.filename), 'rosdoc2.yaml') + if os.path.exists(path): + print(f'Config file already exists at {path}, ' + 'remove it and run again to replace it with the default.') + return + + package_map = create_format_map_from_package(package) + rosdoc_config_file = DEFAULT_ROSDOC_CONFIG_FILE.format_map(package_map) + + with open(path, 'w') as config_file: + config_file.write(rosdoc_config_file) + print('Created rosdoc2.yaml, remember to add \"rosdoc2.yaml\" ' + f'to the \"export\" section in {package.filename}') diff --git a/setup.cfg b/setup.cfg index 6efd27b..8893cb1 100644 --- a/setup.cfg +++ b/setup.cfg @@ -57,6 +57,7 @@ zip_safe = false rosdoc2.verbs = build = rosdoc2.verbs.build:entry_point_data open = rosdoc2.verbs.open:entry_point_data + default_config = rosdoc2.verbs.default_config:entry_point_data console_scripts = rosdoc2 = rosdoc2.main:main