Autobuild overview docs from python scripts
Jammy2211 opened this issue · comments
We have overview Python scripts describing functionality:
https://github.com/Jammy2211/autolens_workspace/tree/release/scripts/overview
We have .rst docs based on these scripts for readthedocs:
https://pyautolens.readthedocs.io/en/latest/overview/overview_1_lensing.html
We should pursue having the .rst doc files build from the python scripts, as we are now running into situations where API changes are meaning certain scripts are not updated properly.
Converting from Python code to .rst should be simply, and can exploit the same formatting and script-to-notebook conversion:
"""
__Grids__
To describe the deflection of light, **PyAutoLens** uses `Grid2D` data structures, which are two-dimensional
Cartesian grids of (y,x) coordinates.
Below, we make and plot a uniform Cartesian grid:
"""
grid_2d = al.Grid2D.uniform(
shape_native=(100, 100),
pixel_scales=0.1, # The pixel-scale describes the conversion from pixel units to arc-seconds.
)
grid_2d_plotter = aplt.Grid2DPlotter(grid=grid_2d)
grid_2d_plotter.figure_2d()
Becomes the following .rst:
Grids
-----
To describe the deflection of light due to the lens galaxy's mass, **PyAutoLens** uses ``Grid2D`` data structures, which
are two-dimensional Cartesian grids of (y,x) coordinates.
Below, we make and plot a uniform Cartesian grid:
.. code-block:: python
grid_2d = al.Grid2D.uniform(
shape_native=(50, 50), pixel_scales=0.05
)
grid_2d_plotter = aplt.Grid2DPlotter(grid=grid_2d)
grid_2d_plotter.figure_2d()
The one snag is what to do with visuals. in the Python script / notebook the Plotter
object is called, but in the .rst we have to manually put the image:
.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/master/docs/overview/images/lensing/grid.png
:width: 400
:alt: Alternative text
Is there a way to have the conversion script automatically output all of the .png files and build these code extracts?
Too complicated.