Skip to content

Commit

Permalink
Clarify directory naming
Browse files Browse the repository at this point in the history
  • Loading branch information
@rkent
rkent committed Apr 1, 2024
1 parent cd49433 commit f7032fd
Showing 1 changed file with 42 additions and 40 deletions.
82 changes: 42 additions & 40 deletions rosdoc2/verbs/build/builders/sphinx_builder.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -161,7 +161,7 @@ def ensure_global(name, default):
from exhale import utils
exhale_args.update({{
# These arguments are required.
"containmentFolder": "{user_sourcedir}/generated",
"containmentFolder": "{sphinx_project_directory}/generated",
"rootFileName": "index.rst",
"rootFileTitle": "C++ API",
"doxygenStripFromPath": "..",
Expand Down Expand Up @@ -220,7 +220,7 @@ def ensure_global(name, default):
#
import os
import sys
sys.path.insert(0, os.path.abspath(os.path.join('{package_src_directory}', '..')))
sys.path.insert(0, os.path.abspath(os.path.join('{python_src_directory}', '..')))
# -- Project information -----------------------------------------------------
Expand Down Expand Up @@ -421,9 +421,9 @@ def build(self, *, doc_build_folder, output_staging_directory):
f"'{self.doxygen_xml_directory}' does not exist.")

package_xml_directory = os.path.dirname(self.build_context.package.filename)
# If 'python_source' is specified, construct 'package_src_directory' from it
# If 'python_source' is specified, construct 'python_src_directory' from it
if self.build_context.python_source is not None:
package_src_directory = \
python_src_directory = \
os.path.abspath(
os.path.join(
package_xml_directory,
Expand All @@ -432,47 +432,48 @@ def build(self, *, doc_build_folder, output_staging_directory):
else:
package_list = setuptools.find_packages(where=package_xml_directory)
if self.build_context.package.name in package_list:
package_src_directory = \
python_src_directory = \
os.path.abspath(
os.path.join(
package_xml_directory,
self.build_context.package.name))
else:
package_src_directory = None
python_src_directory = None

# Check if the user provided a sourcedir.
sourcedir = self.sphinx_sourcedir
if sourcedir is not None:
# Check if the user provided a sphinx directory.
sphinx_project_directory = self.sphinx_sourcedir
if sphinx_project_directory is not None:
# We do not need to check if this directory exists, as that was done in __init__.
logger.info(
f"Note: the user provided sourcedir for Sphinx '{sourcedir}' will be used.")
'Note: the user provided sourcedir for Sphinx '
f"'{sphinx_project_directory}' will be used.")
else:
# If the user does not supply a Sphinx sourcedir, check the standard locations.
standard_sphinx_sourcedir = self.locate_sphinx_sourcedir_from_standard_locations()
if standard_sphinx_sourcedir is not None:
logger.info(
'Note: no sourcedir provided, but a Sphinx sourcedir located in the '
f"standard location '{standard_sphinx_sourcedir}' and that will be used.")
sourcedir = standard_sphinx_sourcedir
sphinx_project_directory = standard_sphinx_sourcedir
else:
# If the user does not supply a Sphinx sourcedir, and there is no Sphinx project
# in the conventional location, i.e. '<package dir>/doc', create a temporary
# Sphinx project in the doc build directory to enable cross-references.
logger.info(
'Note: no sourcedir provided by the user and no Sphinx sourcedir was found '
'in the standard locations, therefore using a default Sphinx configuration.')
sourcedir = os.path.join(doc_build_folder, 'default_sphinx_project')
sphinx_project_directory = os.path.join(doc_build_folder, 'default_sphinx_project')

# Generate rst documents for interfaces
interface_counts = generate_interface_docs(
package_xml_directory,
self.build_context.package.name,
os.path.join(sourcedir, 'generated')
os.path.join(sphinx_project_directory, 'generated')
)
logger.info(f'interface_counts: {interface_counts}')

self.generate_default_project_into_directory(
sourcedir, package_src_directory, interface_counts)
sphinx_project_directory, python_src_directory, interface_counts)

# Collect intersphinx mapping extensions from discovered inventory files.
inventory_files = \
Expand All @@ -487,28 +488,29 @@ def build(self, *, doc_build_folder, output_staging_directory):
if package_name != self.build_context.package.name
]

# Setup rosdoc2 Sphinx file which will include and extend the one in `sourcedir`.
# Setup rosdoc2 Sphinx file which will include and extend the one in
# `sphinx_project_directory`.
self.generate_wrapping_rosdoc2_sphinx_project_into_directory(
doc_build_folder,
sourcedir,
package_src_directory,
sphinx_project_directory,
python_src_directory,
intersphinx_mapping_extensions)

# If the package has python code, then invoke `sphinx-apidoc` before building
has_python = self.build_context.build_type == 'ament_python' or \
self.build_context.always_run_sphinx_apidoc or \
self.build_context.ament_cmake_python
if has_python:
if not package_src_directory or not os.path.isdir(package_src_directory):
if not python_src_directory or not os.path.isdir(python_src_directory):
raise RuntimeError(
'Could not locate source directory to invoke sphinx-apidoc in. '
'If this is package does not have a standard Python package layout, '
"please specify the Python source in 'rosdoc2.yaml'.")
cmd = [
'sphinx-apidoc',
'-o', os.path.relpath(sourcedir, start=doc_build_folder),
'-o', os.path.relpath(sphinx_project_directory, start=doc_build_folder),
'-e', # Document each module in its own page.
package_src_directory,
python_src_directory,
]
logger.info(
f"Running sphinx-apidoc: '{' '.join(cmd)}' in '{doc_build_folder}'"
Expand All @@ -526,7 +528,7 @@ def build(self, *, doc_build_folder, output_staging_directory):
cmd = [
'sphinx-build',
'-c', os.path.relpath(doc_build_folder, start=working_directory),
os.path.relpath(sourcedir, start=working_directory),
os.path.relpath(sphinx_project_directory, start=working_directory),
sphinx_output_dir,
]
logger.info(
Expand Down Expand Up @@ -590,14 +592,14 @@ def locate_sphinx_sourcedir_from_standard_locations(self):
return None

def generate_default_project_into_directory(
self, directory, package_src_directory, interface_counts):
self, directory, python_src_directory, interface_counts):
"""Generate the default project configuration files."""
os.makedirs(directory, exist_ok=True)

package = self.build_context.package
template_variables = {
'package': package,
'package_src_directory': esc_backslash(package_src_directory),
'python_src_directory': esc_backslash(python_src_directory),
'package_version_short': '.'.join(package.version.split('.')[0:2]),
'package_licenses': ', '.join(package.licenses),
'package_authors': ', '.join(set(
Expand All @@ -622,36 +624,36 @@ def generate_default_project_into_directory(

def generate_wrapping_rosdoc2_sphinx_project_into_directory(
self,
directory,
user_sourcedir,
package_src_directory,
doc_build_folder,
sphinx_project_directory,
python_src_directory,
intersphinx_mapping_extensions,
):
"""Generate the rosdoc2 sphinx project configuration files."""
# Copy all user content, like images or documentation files, and
# source files to the wrapping directory
if user_sourcedir:
if sphinx_project_directory:
try:
shutil.copytree(
os.path.abspath(user_sourcedir),
os.path.abspath(directory),
os.path.abspath(sphinx_project_directory),
os.path.abspath(doc_build_folder),
dirs_exist_ok=True)
if self.build_context.build_type == 'ament_python':
# shutil.copy tree will recursively copy an entire
# directory rooted at the provided src directory.
# If we supply package_src_directory as src,
# it will copy the contents within package_src_directory.
# However, we want to copy the package_src_directory itself
# If we supply python_src_directory as src,
# it will copy the contents within python_src_directory.
# However, we want to copy the python_src_directory itself
# such that the python modules will reside within this folder
# at the destination directory.
shutil.copytree(
os.path.abspath(os.path.join(package_src_directory, '..')),
os.path.abspath(directory),
os.path.abspath(os.path.join(python_src_directory, '..')),
os.path.abspath(doc_build_folder),
dirs_exist_ok=True)
except OSError as e:
print(f'Failed to copy user content: {e}')

os.makedirs(directory, exist_ok=True)
os.makedirs(doc_build_folder, exist_ok=True)

package = self.build_context.package
breathe_projects = []
Expand All @@ -661,15 +663,15 @@ def generate_wrapping_rosdoc2_sphinx_project_into_directory(
f'"{esc_backslash(self.doxygen_xml_directory)}"')
template_variables = {
'package_name': package.name,
'package_src_directory': package_src_directory,
'python_src_directory': python_src_directory,
'exec_depends': [exec_depend.name for exec_depend in package.exec_depends]
+ [doc_depend.name for doc_depend in package.doc_depends],
'build_type': self.build_context.build_type,
'always_run_doxygen': self.build_context.always_run_doxygen,
'did_run_doxygen': self.doxygen_xml_directory is not None,
'user_sourcedir': esc_backslash(os.path.abspath(user_sourcedir)),
'sphinx_project_directory': esc_backslash(os.path.abspath(sphinx_project_directory)),
'user_conf_py_filename': esc_backslash(
os.path.abspath(os.path.join(user_sourcedir, 'conf.py'))),
os.path.abspath(os.path.join(sphinx_project_directory, 'conf.py'))),
'breathe_projects': ',\n'.join(breathe_projects) + '\n ',
'intersphinx_mapping_extensions': ',\n '.join(intersphinx_mapping_extensions),
'package': package,
Expand All @@ -679,6 +681,6 @@ def generate_wrapping_rosdoc2_sphinx_project_into_directory(
'package_version_short': '.'.join(package.version.split('.')[0:2]),
}

print(os.path.abspath(os.path.join(directory, 'conf.py')))
with open(os.path.join(directory, 'conf.py'), 'w+') as f:
print(os.path.abspath(os.path.join(doc_build_folder, 'conf.py')))
with open(os.path.join(doc_build_folder, 'conf.py'), 'w+') as f:
f.write(rosdoc2_wrapping_conf_py_template.format_map(template_variables))

0 comments on commit f7032fd

Please sign in to comment.