Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Docs #203

Merged
merged 51 commits into from
Nov 22, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
51 commits
Select commit Hold shift + click to select a range
518639b
First stab at doc structure
robertdstein Nov 21, 2022
fa5df3e
add makefles
robertdstein Nov 21, 2022
a2a529c
add .yml
robertdstein Nov 21, 2022
8fcb28a
fix import rubbish
robertdstein Nov 21, 2022
476bc51
updat
robertdstein Nov 21, 2022
9651dfd
Delete redundant reference
robertdstein Nov 21, 2022
53e93a9
Update rtd
robertdstein Nov 21, 2022
7b4827d
Add docs to readme
robertdstein Nov 21, 2022
c8531d8
Import version/name
robertdstein Nov 21, 2022
4355be1
Add autodoc
robertdstein Nov 21, 2022
a887d68
Update .yml
robertdstein Nov 21, 2022
39ae3ed
Add requirements.txt
robertdstein Nov 21, 2022
5e62f1d
Go for requirements
robertdstein Nov 21, 2022
f2945f0
Go for requirements
robertdstein Nov 21, 2022
651af08
Try again
robertdstein Nov 21, 2022
07fe481
Try again
robertdstein Nov 21, 2022
4305a51
Modify old way
robertdstein Nov 21, 2022
f8fe48f
Modify old way
robertdstein Nov 21, 2022
b8cb542
Modify old way
robertdstein Nov 21, 2022
a3f19d9
hybrid
robertdstein Nov 21, 2022
e91810f
postcheckout
robertdstein Nov 21, 2022
5022d6a
postcheckout
robertdstein Nov 21, 2022
a4014b3
update requirements
robertdstein Nov 21, 2022
d22c275
Try usiung requirements
robertdstein Nov 21, 2022
98db103
try again
robertdstein Nov 21, 2022
8acc8c6
More poetry
robertdstein Nov 21, 2022
fb352fb
More poetry
robertdstein Nov 21, 2022
03b9043
try again
robertdstein Nov 21, 2022
06feed4
Set raw/output dir
robertdstein Nov 21, 2022
c14718c
Update paths
robertdstein Nov 21, 2022
4720932
Try better
robertdstein Nov 21, 2022
9632c4c
Try best
robertdstein Nov 21, 2022
a21c247
Go for .yml
robertdstein Nov 22, 2022
a9130c0
Do not fail on warning
robertdstein Nov 22, 2022
3a27a73
Update index
robertdstein Nov 22, 2022
bd6367d
try real code
robertdstein Nov 22, 2022
5532b7d
Try again again
robertdstein Nov 22, 2022
66e21b8
Delete redundant export
robertdstein Nov 22, 2022
1db1c2a
Real installation instructions
robertdstein Nov 22, 2022
6c1747c
Run doctest in CI
robertdstein Nov 22, 2022
7277e34
Update dependency
robertdstein Nov 22, 2022
e5fa466
Add installation instructions:
robertdstein Nov 22, 2022
4137663
Run doc tests
robertdstein Nov 22, 2022
7cd6186
Install build-essentials
robertdstein Nov 22, 2022
b5ad3d9
try cd
robertdstein Nov 22, 2022
81a9e2d
Try better CI
robertdstein Nov 22, 2022
78729c8
Try betterer
robertdstein Nov 22, 2022
58f9969
viewcode
robertdstein Nov 22, 2022
2ccf8e1
Update docs
robertdstein Nov 22, 2022
50a2f0b
Fix deliberate typo
robertdstein Nov 22, 2022
d1d61de
Bump readme
robertdstein Nov 22, 2022
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion .github/workflows/continous_integration.yml
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ jobs:
- name: install packages
run: |
sudo apt-get update
sudo apt-get install -y sextractor scamp swarp psfex
sudo apt-get install -y sextractor scamp swarp psfex build-essential
sudo ln -s /usr/bin/source-extractor /usr/bin/sex
sudo ln -s /usr/bin/SWarp /usr/bin/swarp
echo `sex --version`
Expand All @@ -67,6 +67,11 @@ jobs:
sudo service postgresql restart
sudo -u postgres psql -c "create user runner; grant all privileges on database postgres to runner; ALTER USER runner WITH SUPERUSER;"

# First make sure the doc tests are up to date
- name: Run doc tests
run: |
poetry run make -C docs/ doctest

# Runs a set of commands using the runners shell
- name: Test the code
env:
Expand Down
19 changes: 19 additions & 0 deletions .readthedocs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
version: 2

build:
os: ubuntu-22.04
tools:
python: "3.10"
jobs:
post_create_environment:
- echo "Command run at 'post_create_environment' step"
- python -m pip install --upgrade --no-cache-dir pip setuptools
- pip install -e .

sphinx:
builder: html
fail_on_warning: false

formats:
- pdf
- epub
26 changes: 2 additions & 24 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,33 +2,11 @@

[![CI](https://github.com/winter-telescope/winterdrp/actions/workflows/continous_integration.yml/badge.svg)](https://github.com/winter-telescope/winterdrp/actions/workflows/continous_integration.yml)
[![Coverage Status](https://coveralls.io/repos/github/winter-telescope/winterdrp/badge.svg?branch=main)](https://coveralls.io/github/winter-telescope/winterdrp?branch=main)
[![Documentation Status](https://readthedocs.org/projects/winterdrp/badge/?version=latest)](https://winterdrp.readthedocs.io/en/latest/?badge=latest)

Open-source modular python package for astronomy image reduction.

in addition to python requirements, winterdrp requires:

* Source-extractor/sextractor
* Swarp
* Scamp

Instructions for .env
1. Copy the `.env.example` file to the root of the project and update the environment variables.
2. Name this file `.env`

# Install Instructions

winterdrp uses poetry for dependency management. You can install the code in the following way:

```
git clone git@github.com:winter-telescope/winterdrp.git
pip install poetry
cd winterdrp
poetry install
```

This will install the combination of python dependencies which we have tested. You can then use winterdrp from the command line:

```python -m winterdrp ......```
Check out our [documentation](https://winterdrp.readthedocs.io/en/latest/?badge=latest) to learn more.

# Testing

Expand Down
20 changes: 20 additions & 0 deletions docs/Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = build

# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
37 changes: 37 additions & 0 deletions docs/make.bat
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
@ECHO OFF

pushd %~dp0

REM Command file for Sphinx documentation

if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build

if "%1" == "" goto help

%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)

%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end

:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

:end
popd
Footer

1 change: 1 addition & 0 deletions docs/requirements.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
-e .[docs]
37 changes: 37 additions & 0 deletions docs/source/conf.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
from winterdrp.paths import package_name, __version__
# Configuration file for the Sphinx documentation builder.

# -- Project information

project = package_name
copyright = '2022, Stein'
author = 'Stein'

release = __version__
version = __version__

# -- General configuration

extensions = [
'sphinx.ext.duration',
'sphinx.ext.doctest',
'sphinx.ext.autodoc',
'sphinx.ext.autosummary',
'sphinx.ext.intersphinx',
"sphinx.ext.viewcode"
]

intersphinx_mapping = {
'python': ('https://docs.python.org/3/', None),
'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
}
intersphinx_disabled_domains = ['std']

templates_path = ['_templates']

# -- Options for HTML output

html_theme = 'sphinx_rtd_theme'

# -- Options for EPUB output
epub_show_urls = 'footnote'
25 changes: 25 additions & 0 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
Welcome to the winterdrp documentation!
=======================================

Winterdrp is a modular, flexible, open-source code to reduce analyse astronomy images, built using python 3.11.

Check out the :doc:`usage` section for further information, including
how to :doc:`installation` the project.

.. note::

This project is under active development.

Contents
--------

.. toctree::
:maxdepth: 2

installation
usage

.. toctree::
:maxdepth: 2

modules
102 changes: 102 additions & 0 deletions docs/source/installation.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
Installation
============

Downloading
-----------

To use winterdrp, first you need to clone it:

.. code-block:: bash

git clone git@github.com:winter-telescope/winterdrp.git


Installing the package
----------------------

You next need to install the package itself. The code is built using python.
We suggest creating a dedicated `conda <https://www.anaconda.com/products/distribution>`_ environment (), but you could also use a virtual environment.

.. code-block:: bash

conda create -n winter_env python=3.10
conda activate winter_env
pip install --upgrade pip

Next you need to actually install winterdrp. We use `poetry <https://python-poetry.org/>`_ to manage dependencies:

.. code-block:: bash

pip install poetry
poetry install winterdrp

Now you should have installed winterdrp. You can check it worked by opening up python and trying to import it:

.. code-block:: bash

python

.. doctest::

>>> from winterdrp.paths import package_name, __version__
>>> print(f"This is the {package_name} package, version {__version__}")
This is the winterdrp package, version 0.4.3

Non-python dependencies
-----------------------

Finally you meed to install any optional dependencies that you might want to use.
We again recommend using conda. Whether you need these dependencies depends on your intended usage of winterdrp.

Dependencies include:

* `source-extractor <https://www.astromatic.net/software/sextractor/>`_ (a.k.a sextractor)
* `scamp <https://www.astromatic.net/software/scamp//>`_
* `swarp <https://www.astromatic.net/software/swarp/>`_
* `psfex <https://www.astromatic.net/software/psfex/>`_
* `postgreSQL <https://www.postgresql.org/download/>`_

PostgreSQL is relatively straightfoward to install via the `official website <https://www.postgresql.org/download/>`_.
The other packages might be more complicated, and will depend on your platform.

astromatic software with apt-get (Linux only)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can use apt-get if you are running :

.. code-block:: bash

sudo apt-get update
sudo apt-get install -y sextractor scamp swarp psfex
sudo ln -s /usr/bin/source-extractor /usr/bin/sex
sudo ln -s /usr/bin/SWarp /usr/bin/swarp

The latter two lines are to ensure that source-extractor/swarp can be called from the command line in the way expected by winterdrp.

astromatic software with conda (Linux, Mac or Windows)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can try installing things via conda:

.. code-block:: bash

conda install -c conda-forge astromatic-source-extractor astromatic-scamp astromatic-swarp astromatic-psfex


Configuring variables
---------------------

winterdrp has several options for execution.
You can pass some of these as arguments, but some e.g tokens or passwords are best included as environment variables.

You can find a full list of variables in `env.example`:

.. literalinclude:: ../../env.example

You can set these variables in the command line:

.. code-block:: bash

export RAW_DATA_DIR=/home/astronomer/rawdata


7 changes: 7 additions & 0 deletions docs/source/modules.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
winterdrp
=========

.. toctree::
:maxdepth: 4

winterdrp
23 changes: 23 additions & 0 deletions docs/source/usage.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
Usage
=====

You can execute winterdrp via the command line:

.. code-block:: bash

python -m winterdrp -p name-of-pipeline -n night-to-reduce

One example is the following:

.. code-block:: bash

python -m winterdrp -p summer

How can you know which pipelines are available? You can check the documentation here: :doc:`winterdrp.pipelines`.
Alternatively, you can check via the code:

.. doctest::

>>> from winterdrp.pipelines import Pipeline
>>> print([x for x in Pipeline.pipelines.keys()])
['wirc', 'summer']
29 changes: 29 additions & 0 deletions docs/source/winterdrp.catalog.kowalski.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
winterdrp.catalog.kowalski package
==================================

Submodules
----------

winterdrp.catalog.kowalski.ps1 module
-------------------------------------

.. automodule:: winterdrp.catalog.kowalski.ps1
:members:
:undoc-members:
:show-inheritance:

winterdrp.catalog.kowalski.tmass module
---------------------------------------

.. automodule:: winterdrp.catalog.kowalski.tmass
:members:
:undoc-members:
:show-inheritance:

Module contents
---------------

.. automodule:: winterdrp.catalog.kowalski
:members:
:undoc-members:
:show-inheritance:
Loading