Resolve "Find a way to add the ju_extensions module to the API documentation"
requested to merge 145-find-a-way-to-add-the-ju_extensions-module-to-the-api-documentation into development
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:
-
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.
- We chose Documenter.jl, a robust documentation generator for Julia, to create a standalone documentation site for the
-
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.
- The generated HTML documentation from Documenter.jl is then parsed and restructured to match the layout of the
Implementation Details:
- The integration process occurs after the Sphinx documentation is built.
- A script included in the Makefile is responsible for:
-
makeLocal.jl
: Building theju_extensions/docs
package. -
make.jl
: Building documentation withDocumenter.jl
'smakedocs()
-
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 theju_extensions
module. -
New features:
- NSGA2.jl Documentation extended
- Integrated julia documentation generator for ju_extensions
- Automatically add ju_extensions documentation to eta_utility docs
Closes #145
Edited by Mikael Hailu