diff --git a/docs/source/about.md b/docs/source/about.md index abbeccc97..1314edd2e 100644 --- a/docs/source/about.md +++ b/docs/source/about.md @@ -10,10 +10,18 @@ function (PSF) modelling technique. The code has been designed to facilitate the inclusion of new or improved processing steps to adapt to advances made in the coming years. +```{figure} https://www.skysurvey.cc/wp-content/uploads/2022/04/UNIONS-Logo-TextBlack-1K-300x82.png +--- +figclass: margin +alt: UNIONS logo +target: https://www.skysurvey.cc/ +--- +``` + The primary application of ShapePipe so far has been to the Ultraviolet -Near-Infrared Optical Northern Survey (UNIONS) data (see {cite:t}`guinot:21` +Near-Infrared Optical Northern Survey (UNIONS) data (see {cite:t}`guinot:22` and Kilbinger et al., in prep). We plan to add features and find new applications for ShapePipe and will update this documentation accordingly. For more details on the first public release -of ShapePipe please see Farrens et al. (in prep). +of ShapePipe please see {cite:t}`farrens:22b`. diff --git a/docs/source/basic_execution.md b/docs/source/basic_execution.md index fade00674..9e7ca63b4 100644 --- a/docs/source/basic_execution.md +++ b/docs/source/basic_execution.md @@ -5,14 +5,14 @@ ShapePipe pipelines are launched and managed via the `shapepipe_run` script. A list of command line arguments can be displayed using the `--help` option: +```{seealso} +:class: margin +The `shapepipe` environment will need to be built and activated in order to run this script (see [Installation](installation.md)). +``` ```bash shapepipe_run --help ``` -```{warning} -The `shapepipe` environment will need to be built and activated in order to run this script (see [Installation](installation.md)). -``` - The options for defining a pipeline are managed via a [configuration file](configuration.md). diff --git a/docs/source/conf.py b/docs/source/conf.py index 8ea294407..72239d138 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -113,7 +113,12 @@ 'use_issues_button': True, 'use_download_button': False, 'use_fullscreen_button': False, + 'use_edit_page_button': True, + 'path_to_docs': 'docs/source', + 'extra_navbar': "

", } +html_collapsible_definitions = True +html_awesome_headerlinks = True # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". @@ -153,4 +158,5 @@ # -- BibTeX Setting ---------------------------------------------- bibtex_bibfiles = ['refs.bib'] -bibtex_default_style = 'alpha' +bibtex_default_style = 'unsrt' +bibtex_reference_style = 'author_year' diff --git a/docs/source/contributors.md b/docs/source/contributors.md index d1f850450..a9ab324ec 100644 --- a/docs/source/contributors.md +++ b/docs/source/contributors.md @@ -7,6 +7,34 @@ possible applications of the package. Below will list the individuals who have contributed to the development of ShapePipe so far. +```{figure} https://avatars.githubusercontent.com/u/6851839?v=4 +--- +figclass: margin +alt: Samuel Farrens +width: 25% +target: https://github.com/sfarrens +--- +Samuel Farrens +``` +```{figure} https://avatars.githubusercontent.com/u/39480528?v=4 +--- +figclass: margin +alt: Axel Guinot +width: 25% +target: https://github.com/aguinot +--- +Axel Guinot +``` +```{figure} https://avatars.githubusercontent.com/u/4549196?v=4 +--- +figclass: margin +alt: Martin Kilbinger +width: 25% +target: https://github.com/martinkilbinger +--- +Martin Kilbinger +``` + ## Maintainers - [Samuel Farrens](https://github.com/sfarrens) : Development lead, core package developer, performance and debugging diff --git a/docs/source/index.rst b/docs/source/index.rst index b70f77905..8a030bfe7 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -4,6 +4,12 @@ ShapePipe .. Include table of contents .. include:: toc.rst +.. figure:: img/cosmostat_logo.jpg + :figclass: margin + :width: 100% + :alt: CosmoStat Logo + :target: http://www.cosmostat.org/ + ShapePipe is a galaxy shape measurement pipeline developed within the |link-to-cosmostat| lab at CEA Paris-Saclay. @@ -13,9 +19,7 @@ we invite you to |link-to-issues| on the GitHub repository an we will do our best to help you. We kindly request that if you use ShapePipe for your academic work that you -cite :cite:`guinot:21` and Farrens et al. (in prep). - -|CS_LOGO| +cite :cite:t:`guinot:22` and :cite:t:`farrens:22b`. .. |link-to-cosmostat| raw:: html @@ -25,8 +29,3 @@ cite :cite:`guinot:21` and Farrens et al. (in prep). open an issue - -.. |CS_LOGO| image:: img/cosmostat_logo.jpg - :width: 45% - :alt: CosmoStat Logo - :target: http://www.cosmostat.org/ diff --git a/docs/source/installation.md b/docs/source/installation.md index 2c9873b49..bfe4e8096 100644 --- a/docs/source/installation.md +++ b/docs/source/installation.md @@ -1,6 +1,6 @@ # Installation -```{important} +```{attention} ShapePipe was not designed to be a stand-alone Python library. Instead users are expected to install the full ShapePipe environment on the system(s) where data should be processed. @@ -8,19 +8,24 @@ data should be processed. ## Standard Installation -The standard installation of ShapePipe manages [dependencies](dependencies.md) -and scripts using a [Conda](https://docs.conda.io/en/latest/) environment. -Therefore, to follow the standard installation Conda must be available on the -system. - ```{tip} +:class: margin Check out [Miniconda](https://docs.conda.io/en/latest/miniconda.html) for a light weight and easy installation of Conda. ``` +The standard installation of ShapePipe manages [dependencies](dependencies.md) +and scripts using a [Conda](https://docs.conda.io/en/latest/) environment. +Therefore, to follow the standard installation Conda must be available on the +system. + The ShapePipe package should first be cloned (or downloaded) from the [GitHub repository](https://github.com/CosmoStat/shapepipe). +```{note} +:class: margin +Developers should simply clone the repository as usual. +``` ```bash git clone -b --depth 1 git@github.com:CosmoStat/shapepipe.git cd shapepipe @@ -32,10 +37,6 @@ where `` is a [latest release](https://github.com/CosmoStat/shapepipe/releases/latest) unless you want to reproduce an older set of results. -```{note} -Developers should simply clone the repository as usual. -``` - Then, the entire ShapePipe environment, including dependencies, can be built using the `install_shapepipe` script as follows. @@ -93,15 +94,15 @@ entire ShapePipe environment. ## Installing the ShapePipe Library Only -```{warning} -Note, this method will not include any system executables or examples. -``` - The ShapePipe library, i.e. the core package not including module dependencies, can be installed in the following ways. After cloning the repository. +```{warning} +:class: margin +Note, this method will not include any system executables or examples. +``` ```bash pip install . ``` diff --git a/docs/source/module_develop.md b/docs/source/module_develop.md index dd82d2e2a..3df8fe88c 100644 --- a/docs/source/module_develop.md +++ b/docs/source/module_develop.md @@ -67,6 +67,12 @@ def example_module(*args): In the specific case of a module that executes an executable available on the system, the module runner should also import the `execute` function. +```{note} +:class: margin +If no `stdout` or `stderr` are provided by the given module, the module +runner should simply return `None, None`. +``` + ```python from shapepipe.modules.module_decorator import module_runner from shapepipe.modules.module_name_package.module_name import ... @@ -84,10 +90,7 @@ def example_module(*args): return stdout, stderr ``` -```{note} -If no `stdout` or `stderr` are provided by the given module, the the module -runner should simply return `None, None`. -``` + The module runner decorator takes the following keyword arguments: diff --git a/docs/source/refs.bib b/docs/source/refs.bib index f2f5c933d..7dcb046c5 100644 --- a/docs/source/refs.bib +++ b/docs/source/refs.bib @@ -318,11 +318,36 @@ @ARTICLE{farrens:22 adsnote = {Provided by the SAO/NASA Astrophysics Data System} } -@article{guinot:21, - author = {{Guinot}, A. and {Kilbinger}, M. and {Farrens}, S. and others}, +@ARTICLE{farrens:22b, + author = {{Farrens}, S. and {Guinot}, A. and {Kilbinger}, M. and {Liaudat}, T. and {Baumont}, L. and {Jimenez}, X. and {Peel}, A. and {Pujol}, A. and {Schmitz}, M. and {Starck}, J. -L. and {Vitorelli}, A.~Z.}, + title = "{ShapePipe: A modular weak-lensing processing and analysis pipeline}", + journal = {arXiv e-prints}, + keywords = {Astrophysics - Instrumentation and Methods for Astrophysics, Astrophysics - Cosmology and Nongalactic Astrophysics}, + year = 2022, + month = jun, + eid = {arXiv:2206.14689}, + pages = {arXiv:2206.14689}, +archivePrefix = {arXiv}, + eprint = {2206.14689}, + primaryClass = {astro-ph.IM}, + adsurl = {https://ui.adsabs.harvard.edu/abs/2022arXiv220614689F}, + adsnote = {Provided by the SAO/NASA Astrophysics Data System} +} + +@ARTICLE{guinot:22, + author = {{Guinot}, Axel and {Kilbinger}, Martin and {Farrens}, Samuel and {Peel}, Austin and {Pujol}, Arnau and {Schmitz}, Morgan and {Starck}, Jean-Luc and {Erben}, Thomas and {Gavazzi}, Raphael and {Gwyn}, Stephen and {Hudson}, Michael J. and {Hiledebrandt}, Hendrik and {Liaudat}, Tobias and {Miller}, Lance and {Spitzer}, Isaac and {Van Waerbeke}, Ludovic and {Cuillandre}, Jean-Charles and {Fabbro}, S{\'e}bastien and {McConnachie}, Alan}, title = "{ShapePipe: a new shape measurement pipeline and weak-lensing application to UNIONS/CFIS data}", - journal = {Submitted to \aap}, - year = 2021, + journal = {arXiv e-prints}, + keywords = {Astrophysics - Cosmology and Nongalactic Astrophysics}, + year = 2022, + month = apr, + eid = {arXiv:2204.04798}, + pages = {arXiv:2204.04798}, +archivePrefix = {arXiv}, + eprint = {2204.04798}, + primaryClass = {astro-ph.CO}, + adsurl = {https://ui.adsabs.harvard.edu/abs/2022arXiv220404798G}, + adsnote = {Provided by the SAO/NASA Astrophysics Data System} } @ARTICLE{harnois:15, @@ -437,33 +462,33 @@ @ARTICLE{jarvis:04 adsnote = {Provided by the SAO/NASA Astrophysics Data System} } -@ARTICLE{jarvis:16, - author = {{Jarvis}, M. and {Sheldon}, E. and {Zuntz}, J. and {Kacprzak}, T. and +@ARTICLE{jarvis:16, + author = {{Jarvis}, M. and {Sheldon}, E. and {Zuntz}, J. and {Kacprzak}, T. and {Bridle}, S.~L. and {Amara}, A. and {Armstrong}, R. and {Becker}, M.~R. and {Bernstein}, G.~M. and {Bonnett}, C. and {Chang}, C. and {Das}, R. and - {Dietrich}, J.~P. and {Drlica-Wagner}, A. and {Eifler}, T.~F. and + {Dietrich}, J.~P. and {Drlica-Wagner}, A. and {Eifler}, T.~F. and {Gangkofner}, C. and {Gruen}, D. and {Hirsch}, M. and {Huff}, E.~M. and - {Jain}, B. and {Kent}, S. and {Kirk}, D. and {MacCrann}, N. and + {Jain}, B. and {Kent}, S. and {Kirk}, D. and {MacCrann}, N. and {Melchior}, P. and {Plazas}, A.~A. and {Refregier}, A. and {Rowe}, B. and - {Rykoff}, E.~S. and {Samuroff}, S. and {S{\'a}nchez}, C. and - {Suchyta}, E. and {Troxel}, M.~A. and {Vikram}, V. and {Abbott}, T. and + {Rykoff}, E.~S. and {Samuroff}, S. and {S{\'a}nchez}, C. and + {Suchyta}, E. and {Troxel}, M.~A. and {Vikram}, V. and {Abbott}, T. and {Abdalla}, F.~B. and {Allam}, S. and {Annis}, J. and {Benoit-L{\'e}vy}, A. and {Bertin}, E. and {Brooks}, D. and {Buckley-Geer}, E. and {Burke}, D.~L. and {Capozzi}, D. and {Carnero Rosell}, A. and {Carrasco Kind}, M. and - {Carretero}, J. and {Castander}, F.~J. and {Clampitt}, J. and + {Carretero}, J. and {Castander}, F.~J. and {Clampitt}, J. and {Crocce}, M. and {Cunha}, C.~E. and {D'Andrea}, C.~B. and {da Costa}, L.~N. and - {DePoy}, D.~L. and {Desai}, S. and {Diehl}, H.~T. and {Doel}, P. and + {DePoy}, D.~L. and {Desai}, S. and {Diehl}, H.~T. and {Doel}, P. and {Fausti Neto}, A. and {Flaugher}, B. and {Fosalba}, P. and {Frieman}, J. and - {Gaztanaga}, E. and {Gerdes}, D.~W. and {Gruendl}, R.~A. and + {Gaztanaga}, E. and {Gerdes}, D.~W. and {Gruendl}, R.~A. and {Gutierrez}, G. and {Honscheid}, K. and {James}, D.~J. and {Kuehn}, K. and - {Kuropatkin}, N. and {Lahav}, O. and {Li}, T.~S. and {Lima}, M. and + {Kuropatkin}, N. and {Lahav}, O. and {Li}, T.~S. and {Lima}, M. and {March}, M. and {Martini}, P. and {Miquel}, R. and {Mohr}, J.~J. and - {Neilsen}, E. and {Nord}, B. and {Ogando}, R. and {Reil}, K. and + {Neilsen}, E. and {Nord}, B. and {Ogando}, R. and {Reil}, K. and {Romer}, A.~K. and {Roodman}, A. and {Sako}, M. and {Sanchez}, E. and {Scarpine}, V. and {Schubnell}, M. and {Sevilla-Noarbe}, I. and - {Smith}, R.~C. and {Soares-Santos}, M. and {Sobreira}, F. and + {Smith}, R.~C. and {Soares-Santos}, M. and {Sobreira}, F. and {Swanson}, M.~E.~C. and {Tarle}, G. and {Thaler}, J. and {Thomas}, D. and - {Walker}, A.~R. and {Wechsler}, R.~H.}, + {Walker}, A.~R. and {Wechsler}, R.~H.}, title = "{The DES Science Verification weak lensing shear catalogues}", journal = {\mnras}, archivePrefix = "arXiv", diff --git a/docs/source/understanding_api.md b/docs/source/understanding_api.md index 47d4a7a9c..33719681f 100644 --- a/docs/source/understanding_api.md +++ b/docs/source/understanding_api.md @@ -1,13 +1,14 @@ # Understanding the API Documentation -This page aims to help ShapePipe users and developers understand the -Application Programming Interface (API) documentation. - ```{note} +:class: margin If you are already familiar with this type of documentation you can skip this page. ``` +This page aims to help ShapePipe users and developers understand the +Application Programming Interface (API) documentation. + ## What Are API Docs? The API documentation is designed to communicate in clear way what each class @@ -18,6 +19,13 @@ with three double quotes `"""`) written in the code. ## Standard API Docs +```{note} +:class: margin +If an optional argument does not explicitly specify the default parameter value +then the user should expect that this means the default will be `None`, `''`, +`[]`, etc. depending on the input data type. +``` + All the classes/functions include a short description of what they do. This is followed by a `Parameters` section containing a bullet point list of the expected input arguments. For each parameter you will see in brackets the @@ -25,12 +33,6 @@ expected input type (e.g. `int`, `float`, `list`, etc.) followed by a brief description of what the argument is for. Parameters listed as *optional* in the brackets do not need to be provided and will default to some predefined value. -```{note} -If an optional argument does not explicitly specify the default parameter value -then the user should expect that this means the default will be `None`, `''`, -`[]`, etc. depending on the input data type. -``` - For functions that return objects a `Returns` section will follow the `Parameters` section. This will provide a brief description of what is provided by this function. Following `Returns` you will always find `Return type`, which