Jammy2211 / PyAutoBuild

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

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.