diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..aa9b76c4 --- /dev/null +++ b/.github/workflows/docs.yml @@ -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 }} \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 5e4ea17a..7d473f37 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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) diff --git a/docs/index.rst b/docs/index.rst index fefc5f33..8feaa644 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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 diff --git a/docs/notebooks/.gitignore b/docs/notebooks/.gitignore new file mode 100644 index 00000000..5e7d2734 --- /dev/null +++ b/docs/notebooks/.gitignore @@ -0,0 +1,4 @@ +# Ignore everything in this directory +* +# Except this file +!.gitignore diff --git a/docs/quickstart.rst b/docs/quickstart.rst index c4f989e5..9ca841a9 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -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 -`_ -directory of the `fermipy-extra -`_ respository. These -notebooks can be browsed as `static web pages -`_ -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. \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt index 25117a01..56679578 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -5,4 +5,8 @@ astropy pyyaml healpy gammapy -sphinx_rtd_theme \ No newline at end of file +sphinx_rtd_theme +rtds_action +nbsphinx +ipython +pypandoc_binary \ No newline at end of file diff --git a/docs/tutorials.rst b/docs/tutorials.rst new file mode 100644 index 00000000..32d0bfd3 --- /dev/null +++ b/docs/tutorials.rst @@ -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 +`_ +directory of the `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 \ No newline at end of file diff --git a/readthedocs.yml b/readthedocs.yml index eabe13f0..a700ad02 100644 --- a/readthedocs.yml +++ b/readthedocs.yml @@ -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