diff --git a/docs/dev/images/moving_code_example.png b/docs/dev/images/moving_code_example.png new file mode 100644 index 00000000..2868b8bc Binary files /dev/null and b/docs/dev/images/moving_code_example.png differ diff --git a/docs/dev/index.rst b/docs/dev/index.rst index 87a7629f..e6de31cb 100644 --- a/docs/dev/index.rst +++ b/docs/dev/index.rst @@ -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 diff --git a/docs/dev/moving_code.rst b/docs/dev/moving_code.rst new file mode 100644 index 00000000..7713b04d --- /dev/null +++ b/docs/dev/moving_code.rst @@ -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 diff --git a/docs/dev/settings.rst b/docs/dev/settings.rst new file mode 100644 index 00000000..5f64abdb --- /dev/null +++ b/docs/dev/settings.rst @@ -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/ diff --git a/docs/stellarphot/index.rst b/docs/stellarphot/index.rst index f7204183..8ecd69a5 100644 --- a/docs/stellarphot/index.rst +++ b/docs/stellarphot/index.rst @@ -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