Skip to content

Resolve "Find a way to add the ju_extensions module to the API documentation"

Summary

This merge request integrates the documentation for the ju_extensions module into the main API documentation, utilizing a two-step approach involving Documenter.jl and custom HTML parsing.

Explain your context

Adding the ju_extensions module to the API documentation proved to be challenging. Initially, using the sphinx-julia extension was considered. However, its limitations led to explore alternative solutions.

Approach:

  1. Documenter.jl for Julia Documentation:

    • We chose Documenter.jl, a robust documentation generator for Julia, to create a standalone documentation site for the ju_extensions module from its docstrings.
  2. Integration with Sphinx Documentation:

    • The generated HTML documentation from Documenter.jl is then parsed and restructured to match the layout of the eta_utility Sphinx documentation.
    • The parsed HTML is inserted into a designated empty ju_extensions page within the API reference section of the Sphinx documentation.

Implementation Details:

  • The integration process occurs after the Sphinx documentation is built.
  • A script included in the Makefile is responsible for:
    • makeLocal.jl: Building the ju_extensions/docs package.
    • make.jl: Building documentation with Documenter.jl's makedocs()
    • htmlparser.py: Running the HTML parser to transform and integrate the generated documentation.

Requirements:

  • This approach necessitates an active Julia installation to build the ju_extensions documentation page.

Changes:

  • Updated the Makefile to include steps for building the ju_extensions documentation and running the HTML parser.
  • Added scripts for parsing and integrating the Julia documentation into the Sphinx structure.
  • Modified the Sphinx configuration to accommodate the new ju_extensions documentation page.

Impact:

  • This change enhances the completeness and usability of the eta_utility documentation by incorporating detailed documentation for the ju_extensions module.

  • New features:

  1. NSGA2.jl Documentation extended
  2. Integrated julia documentation generator for ju_extensions
  3. Automatically add ju_extensions documentation to eta_utility docs

Closes #145

Edited by Mikael Hailu

Merge request reports