Skip to content

Commit

Permalink
Merge pull request #213 from mwcraig/more-dev-docs
Browse files Browse the repository at this point in the history
More dev docs
  • Loading branch information
mwcraig authored Dec 14, 2023
2 parents db3f826 + 2eb4fcb commit ff265a8
Show file tree
Hide file tree
Showing 5 changed files with 83 additions and 28 deletions.
Binary file added docs/dev/images/moving_code_example.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
34 changes: 6 additions & 28 deletions docs/dev/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -43,33 +43,11 @@ These typically need to be done every time you make a contribution.
you need to make additional commits, make sure you push them to your
fork on GitHub. The pull request will be updated automatically.

Some specific examples
~~~~~~~~~~~~~~~~~~~~~~

Adding new settings
~~~~~~~~~~~~~~~~~~~
.. toctree::
:maxdepth: 1

We use combination of `pydantic`_ and `ipyautoui`_ to handle settings in
``stellarphot``. The settings are defined in the ``settings/models.py`` file. Try to
group settings in a logical way. The settings related to photometry are grouped
together in a single `stellarphot.settings.PhotometrySettings` class.

Typically to add new settings you do not need to do much beyond adding a
new class in ``settings/models.py`` and modifying any code that uses those settings to
take the new settings object as an argument. The graphical notebook interface
is generated on the fly from the settings object, so you do not need to write much
new code for that.

For example, the `stellarphot.settings.ApertureSettings` class defines the settings
related to the aperture photometry. It is used in
`stellarphot.gui_tools.SeeingProfileWidget`. The relevant lines are:

.. code-block:: python
self.aperture_settings = ui_generator(ApertureSettings)
self.aperture_settings.show_savebuttonbar = True
self.aperture_settings.path = Path(self.aperture_settings_file_name.value)
self.save_aps = ipw.Button(description="Save settings")
vb.children = [self.aperture_settings_file_name, self.aperture_settings] #, self.save_aps] #, self.in_t, self.out_t]
.. _pydantic: https://docs.pydantic.dev/latest/
.. _ipyautoui: https://maxfordham.github.io/ipyautoui/
settings
moving_code
47 changes: 47 additions & 0 deletions docs/dev/moving_code.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
Moving code from a notebook into a function or class
====================================================

Some of the development of ``stellarphot`` ends up happening in Jupyter
notebooks. Eventually that code really ought to move into a function or
class and ideally have some tests written for it.

This is often relatively straightforward, if somewhat painful.

An outline of the steps required is:

1. Decided how to break up the code in the notebook. When in doubt, start by
breaking the code in the notebook into relatively small chunks.
2. Move the code from the notebook into a function or class into a
``stellarphot`` file. You will need to decide where to put the new
code in ``stellarphot``. You will also need to identify the variables
that are used in the code and pass them as arguments to the function
or class.
3. Import the new function into the notebook you moved the code from. Try to
run the code in the notebook and make sure it still works.
4. Write tests for the new function or class. Put the test into the ``tests``
folder in the same directory as the ``stellarphot`` file you created.


Example
-------

The following example is based on the notebook
``stellarphot/notebooks/photometry/06-transit-fit-template.ipynb``. If you
look at the notebook at `the git commit 05f11bb`_ you will see that it
contains a number of cells that graph the airmass and several other things
below a transit fit. The specific cells are circled in the image below.

.. image:: images/moving_code_example.png
:width: 600

Note that there are not that many inputs to the code in those cells. They need
the photometry table and a few other parameters.

The code in those cells was moved into the function
`stellarphot.plotting.plot_many_factors`. The notebook was modified in
`this commit`_ to drop the code in the cells and replace it with a call to
`stellarphot.plotting.plot_many_factors`.


.. _`the git commit 05f11bb`: https://github.com/feder-observatory/stellarphot/blob/05f11bb0c8e9f32f00a3b90536f297ef4c6ad9ec/stellarphot/notebooks/photometry/06-transit-fit-template.ipynb
.. _`this commit`: https://github.com/feder-observatory/stellarphot/commit/18e1a00a8947b106b6789f5a9c944fe0d81861d5
29 changes: 29 additions & 0 deletions docs/dev/settings.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
Adding new settings
===================

We use combination of `pydantic`_ and `ipyautoui`_ to handle settings in
``stellarphot``. The settings are defined in the ``settings/models.py`` file. Try to
group settings in a logical way. The settings related to photometry are grouped
together in a single `stellarphot.settings.PhotometrySettings` class.

Typically to add new settings you do not need to do much beyond adding a
new class in ``settings/models.py`` and modifying any code that uses those settings to
take the new settings object as an argument. The graphical notebook interface
is generated on the fly from the settings object, so you do not need to write much
new code for that.

For example, the `stellarphot.settings.ApertureSettings` class defines the settings
related to the aperture photometry. It is used in
`stellarphot.gui_tools.SeeingProfileWidget`. The relevant lines are:

.. code-block:: python
self.aperture_settings = ui_generator(ApertureSettings)
self.aperture_settings.show_savebuttonbar = True
self.aperture_settings.path = Path(self.aperture_settings_file_name.value)
self.save_aps = ipw.Button(description="Save settings")
vb.children = [self.aperture_settings_file_name, self.aperture_settings] #, self.save_aps] #, self.in_t, self.out_t]
.. _pydantic: https://docs.pydantic.dev/latest/
.. _ipyautoui: https://maxfordham.github.io/ipyautoui/
1 change: 1 addition & 0 deletions docs/stellarphot/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ Reference/API
.. automodapi:: stellarphot.io
.. automodapi:: stellarphot.photometry.photometry
.. automodapi:: stellarphot.photometry.source_detection
.. automodapi:: stellarphot.plotting
.. automodapi:: stellarphot.settings
.. automodapi:: stellarphot.transit_fitting
.. automodapi:: stellarphot.transit_fitting.gui
Expand Down

0 comments on commit ff265a8

Please sign in to comment.