Align README with src/ package layout and add automated Sphinx/RTD documentation pipeline

[Copilot]

README and project docs were out of sync with the current package structure, and the repo had no automated documentation pipeline. This PR updates module references, introduces Sphinx + Read the Docs config, and adds a docs build workflow on push.

• README alignment with current package structure

  • Added explicit src/pysco package tree.
  • Updated module references to current paths (pysco.plots, pysco.utils, pysco.eryn).
  • Removed stale module mention (lisautils).
  • Added local docs build entrypoint in README.
  • Added link to hosted documentation on GitHub Pages: https://asantini29.github.io/pysco/.

• Sphinx documentation scaffold (RTD theme)

  • Added docs/ with:
    • conf.py (autodoc/napoleon/viewcode + RTD theme)
    • index.rst
    • modules.rst API reference
    • requirements.txt for docs dependencies
  • Configured Sphinx to resolve package imports from src/.
  • Updated docs version handling to read project.version from pyproject.toml (single source of truth).
  • Extended API docs coverage to include pysco.plots.journals.

• Read the Docs configuration

  • Added .readthedocs.yml using docs/conf.py.
  • Configured RTD install to include docs deps and local package.

• Docs CI workflow on push

  • Added .github/workflows/docs.yml to build HTML docs on every push.
  • Included explicit minimal token permissions (contents: read).

• Repo hygiene

  • Added /docs/_build/ to .gitignore to prevent generated docs artifacts from being committed.

# .github/workflows/docs.yml (core behavior)
on:
  push:
    branches: ["**"]

permissions:
  contents: read

jobs:
  build-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: python -m pip install . -r docs/requirements.txt
      - run: python -m sphinx -b html docs docs/_build/html

https://github.com/user-attachments/assets/67482517-372d-4ae2-9d32-fd6819207438

Original prompt

---

This section details on the original issue you should resolve

<issue_title>docs and readme</issue_title>
<issue_description>the readme file has not been updated to follow the new package structure. also, prepare automatic documentation via read the docs and the sphinx theme, and set up a workflow that builds the documentation on push</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes docs and readme #9

---

📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.

[asantini29]

Make sure to include plots.journals in the documentation. Also add in the readme a link to the GitHub page with the built documentation

[Copilot]

Make sure to include plots.journals in the documentation. Also add in the readme a link to the GitHub page with the built documentation

Implemented in commit dbb744e.

• Added pysco.plots.journals to the Sphinx API reference (docs/modules.rst).
• Added the GitHub Pages docs link to the README.

Screenshot: https://github.com/user-attachments/assets/67482517-372d-4ae2-9d32-fd6819207438