Is it possible to build sub-documents while still reference global `..item::` IDs?

[passeris]

I have a CMake project and would like to build individual component specification documents in addition to the entire documentation. I have a CMake target setup and it builds fine, the only problem is that the document is located in a subfolder, when the sphinx-build starts, mlx.traceability does not know about requirements IDs outside of the folder containing the master_doc which is set to the component design document. That leads to warnings like:

[build] WARNING: Item '!REQ-27883' has no reference to source document.

The folder structure is like this:

Project
   software-packages
      compositionA
         componentA (I define the master_doc to be componentA.rst in my CMake target)
         componentB
   requirements-views
      software_requirements.rst (here is where !REQ-27833 is defined)

My CMake target looks like this:

add_custom_target(
    componentA-html
    ${SPHINX_EXECUTABLE}
    -w error.log
    -q
    -b
    html
    -c
    "${BINARY_BUILD_DIR}"
    -d
    "${SPHINX_CACHE_DIR}"
    "${CMAKE_CURRENT_SOURCE_DIR}"
    "${SPHINX_HTML_DIR}/domain/subsystems/driving-functions/Project"
    -D 
    master_doc=componentA
    COMMENT "Building HTML documentation with Sphinx"
)

The variables are defined as follows:

BINARY_BUILD_DIR => /domain/build/_build
SPHINX_CACHE_DIR => /domain/build/_doctrees
CMAKE_CURRENT_SOURCE_DIR => /domain/subsystems/driving-functions/Project/software-packages/compositionA/ComponentA
SPHINX_HTML_DIR => /domain/build/doc/user-doc/html

The above will output an html document to folder Project, but that comes at the price of a warning. If I build the entire domain however (our overall and comprehensive document including all other subsystems), I will not get that warning because mlx knows about the IDs. I'm trying to save time however in builds and would like to rapidly build component level documents, kind of like what AUTOSAR does with their software components like Pwm driver, Com, Rte, and others. These documents are then indenpendently reviewable and stand on their own.

[Letme]

You could use symbolic links (ln -s), to shadow the software_requirements.rst into the software-packages/compositionA/componentA when you build it only for component. That is my first idea, but this is more of a Sphinx build problem, than traceability extension problem.

[JasperCraeghs]

It seems to me that the documentation of your components cannot stand on its own as it's intertwined with information/items located in separate source files in the same repository. We also have components like you and have never considered building their documentation as standalone as it's not feasible.

Different from components, we have libraries that can be shared with silicon SW projects and have standalone requriements, architecture, design, tests, ... We define our libraries in a separate repository and include them as submodules in our silicon SW projects. We build the documentation of our libraries (lib-doc) separately from the documentation of our silicon SW projects (project-doc). Our project-doc has one-directional links to the lib-doc thanks to dedicated external relationships (one per library) we define in the conf.py.

Maybe (some of) your components could be treated as libraries?

Side note 1: The 2 Sphinx plugins we use to reference and include Doxygen documentation both support remote/separated Doxygen documentation of the library. Our project-doc uses the doxylink plugin to link to its own Doxygen documentation and also the Doxygen documentation of its libraries, located separately on our docserver. Our project-doc uses the breathe plugin to include Doxygen documentation inline and also the Doxygen documentation of its libraries.

Side note 2: I recommend sphinx-build --jobs auto to speed up the doc build and -T to debug crashes when a bug in Sphinx or a plugin was triggered.

Please let me know if this helped and ask any follow-up questions.

[JasperCraeghs]

You'll probably be interested in this feature request, which I'll implement when we can spare the resources: #370