docs: include more documentation and docstrings

Author: luabida

.github/workflows/release.yaml

@@ -7,6 +7,10 @@ on:
   pull_request:
     branches: [ main ]
 
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -39,3 +43,55 @@ jobs:
       run: |
         poetry config pypi-token.pypi ${PYPI_TOKEN}
         make release
+
+  docs:
+    runs-on: ubuntu-latest
+
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - uses: conda-incubator/setup-miniconda@v3
+      with:
+        miniforge-version: latest
+        environment-file: conda/dev.yaml
+        channels: conda-forge,nodefaults
+        activate-environment: pysus
+        auto-update-conda: true
+        conda-solver: libmamba
+
+    - name: Install dependencies
+      run: |
+        pip install poetry poetry-plugin-export
+        poetry config virtualenvs.create false
+        poetry install --with docs --extras dbc
+
+    - name: Build docs
+      run: |
+        cd docs
+        make html
+
+    - name: Configure GitHub Pages
+      uses: actions/configure-pages@v5
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: docs/build/html
+
+    - name: Deploy to GitHub Pages
+      if: github.ref == 'refs/heads/main'
+      id: deployment
+      uses: actions/deploy-pages@v4

README.md

@@ -55,6 +55,16 @@ df = sih(state="SP", year=2024, month=[1, 2, 3])
 df = cnes(state="SP", year=2024, month=1)
 ```
 
+### Listing the files
+
+You can also list the files within the dataset to check which files are available to download
+
+```python
+from pysus import list_files
+
+list_files("SINAN")
+```
+
 ### Using the PySUS Client
 
 ```python

docs/requirements.txt

@@ -1,3 +1,4 @@
 nbsphinx
 sphinx
 sphinx-rtd-theme
+standard-imghdr

docs/source/api.rst

@@ -0,0 +1,137 @@
+API Reference
+=============
+
+The ``pysus.api`` package provides a layered architecture for discovering,
+downloading, and reading data from Brazilian public health databases
+(DATASUS). It supports three remote data sources.
+
+Architecture Overview
+---------------------
+
+The package is organized into a hierarchy of abstract base classes and
+concrete implementations::
+
+    pysus/api/
+    ├── __init__.py          # Package entry (re-exports PySUS)
+    ├── client.py            # Main PySUS orchestrator
+    ├── extensions.py        # File format handlers
+    ├── models.py            # Abstract base classes
+    ├── types.py             # Type aliases
+    ├── _impl/
+    │   └── databases.py     # High-level convenience functions
+    ├── ducklake/            # S3 DuckLake catalog client
+    ├── ftp/                 # FTP client
+    └── dadosgov/            # dados.gov.br API client
+
+Quick Start
+-----------
+
+The simplest way to use PySUS is via the high-level convenience
+functions::
+
+    from pysus import sinan
+
+    df = sinan(disease="dengue", year=2023)
+
+Or with the async API::
+
+    from pysus.api.client import PySUS
+
+    async with PySUS() as pysus:
+        files = await pysus.query(dataset="sinan", group="DENG", year=2023)
+        for f in files:
+            await pysus.download(f)
+
+
+Main Client
+-----------
+
+.. automodule:: pysus.api.client
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Types
+-----
+
+.. automodule:: pysus.api.types
+   :members:
+   :undoc-members:
+
+File Format Handlers
+--------------------
+
+.. automodule:: pysus.api.extensions
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Abstract Base Models
+--------------------
+
+.. automodule:: pysus.api.models
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+High-Level Data Functions
+-------------------------
+
+.. automodule:: pysus.api._impl.databases
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+DuckLake Client
+---------------
+
+.. automodule:: pysus.api.ducklake.client
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pysus.api.ducklake.catalog
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pysus.api.ducklake.models
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+FTP Client
+----------
+
+.. automodule:: pysus.api.ftp.client
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pysus.api.ftp.databases
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pysus.api.ftp.models
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+DadosGov Client
+---------------
+
+.. automodule:: pysus.api.dadosgov.client
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pysus.api.dadosgov.databases
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pysus.api.dadosgov.models
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/conf.py

@@ -12,13 +12,10 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../.."))
 
 # -- General configuration ------------------------------------------------
 
@@ -33,9 +30,14 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
     "nbsphinx",
 ]
 
+intersphinx_mapping = {
+    "sqlalchemy": ("https://docs.sqlalchemy.org/en/20/", None),
+}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]