Add documentation

.github/workflows/build-docs-tests.yml

@@ -0,0 +1,28 @@
+name: test-doc
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+  # Allows to run this workflow manually from the Actions tab
+  workflow_dispatch:
+jobs:
+  # checks that the docs build (it executes the notebooks)
+  test-doc:
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout branch ${{ github.head_ref }}"
+        uses: actions/checkout@v4
+      - name: "Set up Python on Ubuntu"
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.12
+      - name: "Test doc"
+        run: |
+          sudo apt-get install pandoc
+          python3 -m pip install --upgrade pip setuptools
+          pip install .[docs,recommended,notebooks]
+          cd ./docs
+          make html

.github/workflows/publish-docs.yml

@@ -0,0 +1,31 @@
+name: deploy-documentation
+on:
+  push:
+    tags:
+      - v*
+  # Allows to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  deploy-doc:
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout branch ${{ github.head_ref }}"
+        uses: actions/checkout@v4
+      - name: "Set up Python on Ubuntu"
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.12
+      - name: "Build doc"
+        run: |
+          # Build the doc
+          python3 -m pip install --upgrade pip setuptools
+          pip install .[docs,recommended,notebooks]
+          sudo apt-get install pandoc
+          cd ./docs
+          make html
+      - name: "Publish doc on github pages (commit on branch gh-pages)"
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: gh-pages
+          folder: docs/_build/html/

.gitignore

@@ -32,4 +32,8 @@ conda-recipe/ipyaladin
 
 # Python tests
 .pytest_cache/
-.ruff_cache/
+.ruff_cache/
+
+# Documentation
+docs/_build/
+docs/_collections/

docs/Makefile

@@ -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     = .
+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)

docs/community/community.md

@@ -0,0 +1,78 @@
+# Community
+
+Ipyaladin is developed by the Strasbourg Astronomical Data Centre. If it was useful for your
+research, please consider [citing it](https://aladin.cds.unistra.fr/AladinLite/ipyaladin/#acknowledgement).
+
+## Contributions
+
+Contributions are welcome, you can for example:
+
+- open an issue if you find a bug or would like a new feature,
+- work on one of the open issues that have been discussed and milestoned
+- improve the documentation
+
+## Development installation
+
+To start developing `ipyaladin`, clone the repository and do
+
+```sh
+pip install pre-commit
+pre-commit install
+npm run dev
+```
+
+This will listen to any changes made in the python and javascript sides of the widget.
+You can live-develop in a notebook application and your changes will be affected on
+kernel restarts.
+
+We use pre-commit with `Ruff` for formatting the python files, and `husky` with
+`prettier` for the other files. This means than before accepting you commits, you'll
+see if any change is needed. If it is the case, apply the requested changes, `git add`
+the files again, and attempt to commit until all the checks pass.
+
+## Running the tests
+
+There are different tests in the module.
+
+### Python tests
+
+To run the python tests, do:
+
+```sh
+python -m pytest
+```
+
+### Javascript tests
+
+To run the javascript tests, do:
+
+```sh
+npm run start-test-server
+```
+
+then in an other terminal,
+
+```sh
+npm run js-test
+```
+
+### Check that the documentation still builds
+
+You'll need `pandoc`, see https://pandoc.org/installing.html
+Then,
+
+```sh
+pip install .[docs]
+cd docs
+make clean html
+```
+
+## How does it work
+
+`ipyaladin` wraps `Aladin-Lite` into notebooks thanks to `anywidgets`. The useful
+documentation pages are:
+
+- [anywidget](https://anywidget.dev/)
+- [Aladin-Lite public API](https://cds-astro.github.io/aladin-lite/)
+- [Traitlets](https://traitlets.readthedocs.io/en/stable/) (they are used to share
+  information between the python and javascript sides)

docs/conf.py

@@ -0,0 +1,134 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import tomllib
+from pathlib import Path
+
+with Path.open("../pyproject.toml", "rb") as config:
+    toml = tomllib.load(config)
+import datetime
+from ipyaladin import __version__, Aladin
+
+project = toml["project"]["name"]
+author = "Strasbourg Astronomical Date Centre (CDS)"
+copyright = f"{datetime.datetime.now().year}, {author}"  # noqa: A001
+release = __version__
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+# By default, highlight as Python 3.
+highlight_language = "python3"
+
+extensions = []
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinxcontrib.collections",
+    # To support Numpy docstrings, we use this extension:
+    "numpydoc",
+    "nbsphinx",
+    "sphinx_copybutton",
+    "sphinx_gallery.load_style",
+    "autoapi.extension",
+    "myst_parser",
+]
+
+jupyterlite_config = "jupyterlite_config.json"
+
+autoapi_dirs = ["../src"]
+autoapi_options = ["members", "show-module-summary"]
+
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/", None),
+    "astropy": ("http://docs.astropy.org/en/latest/", None),
+    "matplotlib": ("https://matplotlib.org/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "regions": ("https://astropy-regions.readthedocs.io/en/stable", None),
+}
+
+source_suffix = [".rst", ".md"]
+
+# The master toctree document.
+master_doc = "index"
+
+# -- Add the notebooks to Sphinx root folder with collections ----------------
+
+collections = {
+    "notebooks": {
+        "driver": "copy_folder",
+        "source": "../examples/",
+        "target": "notebooks",
+        "ignore": [".ipynb_checkpoints/*"],
+    }
+}
+
+# this allows to set thumbnails for the notebooks
+notebooks = Path().glob("../examples/*.ipynb")
+notebooks = [
+    str(notebook).split("/")[-1].replace(".ipynb", "") for notebook in notebooks
+]
+thumbnail_path = "_static/notebooks_thumbnails/"
+collections_path = "_collections/notebooks/"
+nbsphinx_thumbnails = {
+    f"{collections_path}{notebook}": f"{thumbnail_path}{notebook.split('_')[0]}.png"
+    for notebook in notebooks
+}
+
+# -- Document Init Options ---------------------------------------------------
+
+init_options = Aladin().traits(only_init=True)
+
+with Path.open("user_documentation/init_options.csv", "w"):
+    pass  # flush the file
+
+with Path.open("user_documentation/init_options.csv", "a") as f:
+    for k, v in init_options.items():
+        f.write(f"{k};{v.default_value};{v.help}\n")
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+language = "en"
+
+html_static_path = ["_static"]
+
+html_theme = "pydata_sphinx_theme"
+html_favicon = "_static/aladin-logo.svg"
+
+html_theme_options = {
+    "show_nav_level": 2,
+    "show_toc_level": 3,
+    "content_footer_items": ["last-updated"],
+    "github_url": "https://github.com/cds-astro/ipyaladin",
+    "external_links": [
+        {"name": "Aladin", "url": "https://aladin.cds.unistra.fr/aladin.gml"},
+        {
+            "name": "Changelog",
+            "url": "<https://github.com/cds-astro/ipyaladin/releases>",
+        },
+    ],
+    "logo": {
+        "alt-text": "Ipyaladin documentation - Home",
+        "text": "Ipyaladin documentation",
+        "image_light": "_static/ipyaladin_light.png",
+        "image_dark": "_static/ipyaladin_dark.png",
+    },
+    "back_to_top_button": True,
+    "pygments_dark_style": "lightbulb",  # chose from higher contrasts for accessibility
+    "pygments_light_style": "default",
+}

docs/getting_started/getting_started.rst

@@ -0,0 +1,60 @@
+###############
+Getting Started
+###############
+
+************
+Installation
+************
+
+Released versions
+~~~~~~~~~~~~~~~~~
+
+To get the latest version of ``ipyaladin`` you can either use ``pip``,
+
+.. code-block::
+
+    pip install ipyaladin
+
+or ``conda-forge``,
+
+.. code-block::
+
+    conda install ipyaladin -c conda-forge
+
+and you're all set! 
+
+Unreleased version
+~~~~~~~~~~~~~~~~~~
+
+To install the unreleased version, you will need npm, see its webpages for installation
+instructions `https://www.npmjs.com/ <https://www.npmjs.com/>`_.
+
+Then, download the ``ipyaladin`` github repository. From the root of the repository,
+do 
+
+.. code-block::
+
+    npm run dev
+
+You can then close the terminal with ``ctrl+c`` and the unreleased version of
+ ``ipyaladin`` is installed on your machine.
+
+
+****************
+Using the widget
+****************
+
+You can open a notebook and instantiate an ``ipyaladin`` widget:
+
+.. code-block:: python
+
+    from ipyaladin import Aladin
+    Aladin()
+
+A widget should appear below this cell. See the ``getting started`` notebook example 
+for a bit mot instantiation options, 
+
+.. nbgallery::
+    ../_collections/notebooks/01_Getting_Started
+
+for a more detailed tour of ``ipyaladin``, have a look at the ``User Guide`` section.