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

Docs notebooks #606

Merged
merged 20 commits into from
Aug 20, 2024
Merged
Changes from all commits
Commits
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
70 changes: 70 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
name: Docs
on: [push, release]

jobs:
notebooks:
name: "Build the notebooks for the docs"
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
persist-credentials: false # otherwise, the token used is the GITHUB_TOKEN, instead of your personal token
fetch-depth: 0 # otherwise, you will failed to push refs to dest repo
#- name: Set up Python
# uses: actions/setup-python@v5
# with:
# python-version: 3.9
- name: Checkout
uses: actions/checkout@v4
with:
repository: fermiPy/fermipy-extra
path: fermipy-extra
- name: Setup environment
uses: conda-incubator/setup-miniconda@v3
with:
activate-environment: fermipy
auto-activate-base: false
architecture: "x64"
miniforge-version: latest
python-version: 3.9
environment-file: environment.yml
- name: Install additional packages
shell: bash -l {0}
run: |
mamba install -n fermipy -c conda-forge jupytext nbconvert jupyterthemes notebook ipykernel
pip install -e .
- name: Execute the notebooks
shell: bash -l {0}
run: |
# Make sure we fail in case of error
set -e
ls fermipy-extra/notebooks
rm fermipy-extra/notebooks/index.ipynb
rm fermipy-extra/notebooks/dSphs.ipynb
jupytext --execute fermipy-extra/notebooks/*.ipynb
mv fermipy-extra/notebooks/*.ipynb docs/notebooks/
ls docs/notebooks
# - name: Create function gallery
# #shell: bash -l {0}
# run: |
# # move to the scripts directory
# cd scripts
# # now generate the function docs
# python generate_func_docs.py
# cd ..
# ls docs/notebooks
- uses: actions/upload-artifact@v4
with:
name: notebooks-for-${{ github.sha }}
path: docs/notebooks
- name: Sleep for 5 min
uses: juliangruber/sleep-action@v1
with:
time: 5m
- name: Trigger RTDs build
uses: dfm/rtds-action@main
with:
webhook_url: ${{ secrets.RTDS_WEBHOOK_URL }}
webhook_token: ${{ secrets.RTDS_WEBHOOK_TOKEN }}
commit_ref: ${{ github.ref }}
17 changes: 17 additions & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
@@ -55,6 +55,7 @@
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'nbsphinx',
'sphinx.ext.mathjax',
'sphinx.ext.autodoc',
'sphinx.ext.viewcode',
@@ -75,6 +76,22 @@

intersphinx_cache_limit = 10

if "GITHUB_TOKEN" in os.environ:

extensions.append("rtds_action")

# The path where the artifact should be extracted
# Note: this is relative to the conf.py file!
rtds_action_path = "notebooks"
# # The "prefix" used in the `upload-artifact` step of the action
rtds_action_artifact_prefix = "notebooks-for-"

rtds_action_github_repo = "fermiPy/fermipy"

# # A GitHub personal access token is required, more info below
rtds_action_github_token = os.environ["GITHUB_TOKEN"]

rtds_action_error_if_missing = True

#intersphinx_mapping = {}
#intersphinx_mapping['astropy'] = ('http://docs.astropy.org/en/latest/', None)
2 changes: 2 additions & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
@@ -41,6 +41,7 @@ perform different analysis operations.

For instructions on installing Fermipy see the :ref:`install` page.
For a short introduction to using Fermipy see the :ref:`quickstart`.
For more detailed examples see the :ref:`tutorials`.

Getting Help
------------
@@ -71,6 +72,7 @@ Documentation Contents
team
install
quickstart
tutorials
config
output
fitting
4 changes: 4 additions & 0 deletions docs/notebooks/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Ignore everything in this directory
*
# Except this file
!.gitignore
46 changes: 1 addition & 45 deletions docs/quickstart.rst
Original file line number Diff line number Diff line change
@@ -399,48 +399,4 @@ instance of :py:class:`~fermipy.gtanalysis.GTAnalysis`.
Using :py:meth:`~fermipy.gtanalysis.GTAnalysis.load_roi` is generally
faster than :py:meth:`~fermipy.gtanalysis.GTAnalysis.create` when an
analysis instance already exists.

IPython Notebook Tutorials
--------------------------

Additional tutorials with more detailed examples are available as
IPython notebooks in the `notebooks
<https://github.com/fermiPy/fermipy-extra/tree/master/notebooks/>`_
directory of the `fermipy-extra
<https://github.com/fermiPy/fermipy-extra>`_ respository. These
notebooks can be browsed as `static web pages
<http://nbviewer.jupyter.org/github/fermiPy/fermipy-extra/blob/master/notebooks/index.ipynb>`_
or run interactively by downloading the fermipy-extra repository and
running ``jupyter notebook`` in the notebooks directory:

.. code-block:: bash
$ git clone https://github.com/fermiPy/fermipy-extra.git
$ cd fermipy-extra/notebooks
$ jupyter notebook index.ipynb
Note that this will require you to have both ipython and jupyter
installed in your python environment. These can be installed in a
conda- or pip-based installation as follows:

.. code-block:: bash
# Install with conda
$ conda install ipython jupyter
# Install with pip
$ pip install ipython jupyter
One can also run the notebooks from a docker container following the
:ref:`dockerinstall` instructions:

.. code-block:: bash
$ git clone https://github.com/fermiPy/fermipy-extra.git
$ cd fermipy-extra
$ docker pull fermipy/fermipy
$ docker run -it --rm -p 8888:8888 -v $PWD:/workdir -w /workdir fermipy/fermipy
After launching the notebook server, paste the URL that appears into
your web browser and navigate to the *notebooks* directory.
analysis instance already exists.
6 changes: 5 additions & 1 deletion docs/requirements.txt
Original file line number Diff line number Diff line change
@@ -5,4 +5,8 @@ astropy
pyyaml
healpy
gammapy
sphinx_rtd_theme
sphinx_rtd_theme
rtds_action
nbsphinx
ipython
pypandoc_binary
44 changes: 44 additions & 0 deletions docs/tutorials.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
.. _tutorials:

Tutorials
=========

This page collects various python notebooks that demonstrate how to use
fermipy. These notebooks are available in the `notebooks
<https://github.com/fermiPy/fermipy-extra/tree/master/notebooks/>`_
directory of the `fermipy-extra
<https://github.com/fermiPy/fermipy-extra>`_ respository. These
notebooks can be run interactively by downloading the fermipy-extra
repository and running ``jupyter notebook`` in the notebooks directory:

.. code-block:: bash
$ git clone https://github.com/fermiPy/fermipy-extra.git
$ cd fermipy-extra/notebooks
$ jupyter notebook index.ipynb
Note that this will require you to have both ipython and jupyter
installed in your python environment. These can be installed in a
conda- or pip-based installation as follows:

.. code-block:: bash
# Install with conda
$ conda install ipython jupyter
# Install with pip
$ pip install ipython jupyter
Here is a list of available notebooks:

.. toctree::
:titlesonly:

notebooks/SMC.ipynb
notebooks/pg1553.ipynb
notebooks/optimize_model.ipynb
notebooks/gtools_customize.ipynb
notebooks/file_function_examples.ipynb
notebooks/phase_analysis.ipynb
notebooks/ic443.ipynb
notebooks/draco.ipynb
6 changes: 3 additions & 3 deletions readthedocs.yml
Original file line number Diff line number Diff line change
@@ -8,7 +8,7 @@ version: 2
build:
os: ubuntu-22.04
tools:
python: "3.8"
python: "3.9"

# Build documentation in the "docs/" directory with Sphinx
sphinx:
@@ -35,5 +35,5 @@ python:
- docs
#system_packages: true

sphinx:
configuration: docs/conf.py
#sphinx:
# configuration: docs/conf.py