Sphinx documentation #94

FedericoBerlfein · 2024-11-06T19:13:12Z

Adding Sphinx documentation files. This is the first version, still need to make a few checks before merging.

FedericoBerlfein · 2024-11-08T18:58:25Z

Latest changes could use an initial review. Some known issues:

Some of the documentation style is not consistent with each other (example: how function arguments are written in docstring), causing differences between documentation of functions.
Could not create the HTML file for the instrument_params file. I think this has something to do with the fact that the code contains no functions/classes, so it is being skipped by Sphinx.

Despite this, I think I could benefit from some initial feedback on the structure of the documentation, or anything that could be missing

aguinot

It looks really good, nice work!
As you will some of my comment are not directed to you but more on things that we should discuss as group, so don't worry if you don't have the answer.
I really like the display of the functions with the docstrings and the link to the code source !! 👍

Some general minor comments (maybe for later):

Is it possible to change the theme? I found this a bit "sad" 😅
It looks like the name The Euclid-like ImSim Module too long and module appears on a separate line. Maybe changing the theme would solve the problem but at the moment it looks a bit confusing.

in the Module Index only euclidlike_imsim appears and no euclidlike
Probably related to the comment above, when you search for something it looks through euclidlike_imsim and the scripts but not the euclidlike module. I tied with words: psf, bandpass
That might also be related to the theme. Only some of the functions appears but not all of them. Like for example some of the WCS functions are not listed.

docs/_build/html/_sources/examples.rst.txt

docs/_build/html/_sources/overview.rst.txt

aguinot · 2024-11-08T19:26:58Z

CHANGELOG.rst

@@ -0,0 +1,3 @@
+Changes from v0.0.0 to v0.0.1


Not a comment to you specifically.
We should discuss this at some point. But I think it would be more appropriate to use v0.1.0 or even v1.0.0.
We should chat about that as a group.

Change 0.9.0

aguinot · 2024-11-08T19:29:34Z

docs/conf.py

Also not a comment for you.
We should review this page in the group.

aguinot · 2024-11-08T19:30:07Z

docs/conf.py

+import euclidlike_imsim
+
+project = 'GalSim-Euclid-Like'
+copyright = '2024, Rachel Mandelbaum, Axel Guinot, Federico Berlfein, Andy Park, Xiangchong Li, Michael Troxel, Tianqing Zhang'


I think this should, somehow, include a reference to Euclid.

Rachel will ask once documentation is live.

aguinot · 2024-11-08T19:31:22Z

docs/conf.py

+project = 'GalSim-Euclid-Like'
+copyright = '2024, Rachel Mandelbaum, Axel Guinot, Federico Berlfein, Andy Park, Xiangchong Li, Michael Troxel, Tianqing Zhang'
+author = 'Rachel Mandelbaum, Axel Guinot, Federico Berlfein, Andy Park, Xiangchong Li, Michael Troxel, Tianqing Zhang'
+release = '0.0.1'


Would it be to have a VERSION file and get the value from this file?
I am just thinking that would avoid having to change the version number in multiple places to avoid confusion.

This would be cleaner yes. In GalSim the version lives inside the galsim folder, in our case we have euclidlike and euclidlike_imsim. Do we want the version to then live in the GalSim-Euclid-Like home directory then? Or also live in euclidlike.

Having both in the same place makes things a little more tricky but I think I would use one versioning for both and probably include it in GalSim-Euclid-Like. But I am open to other suggestions.

Make VERSION file.

aguinot · 2024-11-08T19:34:04Z

docs/overview.rst

This comment would apply to the readme.
Should we add a section like contributing? To make it clear that the code is fully public and not driven by Euclid and everyone is free to propose/implement new things?

FedericoBerlfein · 2024-11-14T22:20:44Z

Further updates to address some comments, mainly:

Updated theme: same as that used in GalSim
Added version to euclidlike module. This also included a small addition to euclidlike __init__.py file.
Homogenized docstrings across functions in euclidlike. Some functions used "Args", others "Parameters". Spacing in some of them was also not consistent. Added Returns to Bandpass docstring.
Fixed broken links. This involved adding a new python file called gh-link.py to docs. This allows to easily link files from anywhere in the repo.
Added autosection label, this allows us to reference rst files from their header.

Potential issues and changes:

The previous "Installation Instructions" link in the main page's README no longer directs you anywhere. Previously it directed you to the INSTALL.rst file in the github repo. However, in the github pages, this would direct you to the github repo when clicked, rather than to the installation instructions html page. So for now the README in the github repo does not link to the installation file, it just says which file it is. In the github pages, it should link it to the appropiate html page.
For now the version is only under the euclidlike module. I tried having a single version python file under the root of the repo, but was getting an error when trying to access it from each module (euclidlike or euclidlike_imsim). So for now I only have it in euclidlike. Need to discuss this with group. In addition, pyproject.toml can't read the version directly from the python file, so it needs to be inputed manually for now. Could not find a clean solution to this issue.

FedericoBerlfein · 2024-11-27T17:17:15Z

Made last couple of changes based on last weeks conversation. Mainly:

Changed version number to 0.9.0
Made VERSION txt file in repo root.
Added _version.py file to euclidlike_imsim
Added basic installation instructions in README.rst
Changed "classes and functions" section to "API" in euclidlike and euclidlike_imsim

I think this PR is ready for a final review and potential merge.

rmandelb

Just two small issues I noted in the documentation of the examples. I'm hitting "approve" because you might be able to fix it easily and then you can go ahead and merge.

rmandelb · 2024-12-04T16:57:28Z

docs/examples.rst

+
+:gh-link:`end_to_end_demo.py <examples/end_to_end_demo.py>`
+
+This first demo is the euclidlike-equivalent of  _`demo 13 <https://github.com/GalSim-developers/GalSim/blob/main/examples/demo13.py>`_ in ``GalSim``. This demo uses the Euclid-like PSF, WCS, and background noise to produce a realistic scene of galaxies and stars as observed from a Euclid-like Telescope. 


Something is going wrong with this line, if you look at the html it produces on your branch, but I'm not sure how to fix it.

rmandelb · 2024-12-04T16:57:50Z

docs/examples.rst

+
+This first demo is the euclidlike-equivalent of  _`demo 13 <https://github.com/GalSim-developers/GalSim/blob/main/examples/demo13.py>`_ in ``GalSim``. This demo uses the Euclid-like PSF, WCS, and background noise to produce a realistic scene of galaxies and stars as observed from a Euclid-like Telescope. 
+
+** Features introduced in the Python file**:


These asterisks are not doing what was intended (if you look at the html it produces)

Initial skeleton for Sphinx docs

da6b419

FedericoBerlfein self-assigned this Nov 6, 2024

FedericoBerlfein linked an issue Nov 6, 2024 that may be closed by this pull request

Make documentation #76

Closed

Federico Berlfein and others added 4 commits November 6, 2024 14:50

Changed file structure

251394f

Remove docs/_build from .gitignore

1133d67

Fix missing _build directory

6454870

Updated structure

7e9b74b

aguinot reviewed Nov 8, 2024

View reviewed changes

Federico Berlfein added 4 commits November 14, 2024 15:59

Fixed broken links, updated theme

f0621d7

Made parameters in docstring consistent

d1509d4

Small changes to headings for euclidlike_imsim

6578ca4

Small change to main README

c64a29c

Small changes to versioning, install instructions, API name

b87de69

Federico Berlfein added 2 commits November 27, 2024 12:30

Fix bug with reading version

eb0ca64

Missing os import

cde4f87

aguinot approved these changes Dec 4, 2024

View reviewed changes

rmandelb approved these changes Dec 4, 2024

View reviewed changes

Fix broken link, broken bold font

6c7d4f1

rmandelb merged commit 373eb17 into main Dec 4, 2024
2 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Sphinx documentation #94

Sphinx documentation #94

FedericoBerlfein commented Nov 6, 2024

FedericoBerlfein commented Nov 8, 2024 •

edited

Loading

aguinot left a comment

aguinot Nov 8, 2024

FedericoBerlfein Nov 20, 2024

aguinot Nov 8, 2024

aguinot Nov 8, 2024

FedericoBerlfein Nov 20, 2024

aguinot Nov 8, 2024

FedericoBerlfein Nov 8, 2024

aguinot Nov 9, 2024 •

edited

Loading

FedericoBerlfein Nov 20, 2024

aguinot Nov 8, 2024

FedericoBerlfein commented Nov 14, 2024 •

edited

Loading

FedericoBerlfein commented Nov 27, 2024 •

edited

Loading

rmandelb left a comment

rmandelb Dec 4, 2024

FedericoBerlfein Dec 4, 2024

rmandelb Dec 4, 2024

FedericoBerlfein Dec 4, 2024


		:gh-link:`end_to_end_demo.py <examples/end_to_end_demo.py>`

		This first demo is the euclidlike-equivalent of _`demo 13 <https://github.com/GalSim-developers/GalSim/blob/main/examples/demo13.py>`_ in ``GalSim``. This demo uses the Euclid-like PSF, WCS, and background noise to produce a realistic scene of galaxies and stars as observed from a Euclid-like Telescope.


		This first demo is the euclidlike-equivalent of _`demo 13 <https://github.com/GalSim-developers/GalSim/blob/main/examples/demo13.py>`_ in ``GalSim``. This demo uses the Euclid-like PSF, WCS, and background noise to produce a realistic scene of galaxies and stars as observed from a Euclid-like Telescope.

		Features introduced in the Python file:

Sphinx documentation #94

Sphinx documentation #94

Conversation

FedericoBerlfein commented Nov 6, 2024

FedericoBerlfein commented Nov 8, 2024 • edited Loading

aguinot left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aguinot Nov 9, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

FedericoBerlfein commented Nov 14, 2024 • edited Loading

FedericoBerlfein commented Nov 27, 2024 • edited Loading

rmandelb left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

FedericoBerlfein commented Nov 8, 2024 •

edited

Loading

aguinot Nov 9, 2024 •

edited

Loading

FedericoBerlfein commented Nov 14, 2024 •

edited

Loading

FedericoBerlfein commented Nov 27, 2024 •

edited

Loading