From 92b2a02622d9ad57020893ba017d2a289691fabb Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 1 Nov 2026 16:09:16 +0000 Subject: [PATCH] Docs: lead Start Here with natural language or Python Start Here keeps the galaxy-structure opening, then a 'Natural Language or Python' section: the start-here prompt for the autogalaxy_assistant, access/free options, why natural language and that the Python API is not going anywhere (HowToGalaxy teaches the science). index.md and README Getting Started are restructured to match, the New User Guide's assistant boilerplate becomes one paragraph, and the copyable nl-prompt box is ported from PyAutoFit. No new Sphinx warnings (115 on main and branch). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016nhQ8QgLw3SZjRMSaX3v5z --- README.md | 34 ++++++++++--- docs/_static/pyautogalaxy.css | 59 ++++++++++++++++++++++ docs/conf.py | 12 ++++- docs/index.md | 32 +++++++++--- docs/overview/overview_1_start_here.md | 47 +++++++++++++---- docs/overview/overview_2_new_user_guide.md | 13 ++--- 6 files changed, 163 insertions(+), 34 deletions(-) create mode 100644 docs/_static/pyautogalaxy.css diff --git a/README.md b/README.md index d200f9f8f..6ea004176 100644 --- a/README.md +++ b/README.md @@ -27,21 +27,39 @@ ## Getting Started -### Human-Readable Documentation and Examples +### Natural Language or Python -The following human-readable documentation and examples are useful for new starters: +You can use **PyAutoGalaxy** by describing what you want in natural language, through the +[**PyAutoGalaxy AI Assistant**](https://github.com/PyAutoLabs/autogalaxy_assistant), or by writing Python yourself. Both +routes use the same software. To start in natural language, paste this prompt into Claude Code, Codex or another AI +coding agent: + +Starting prompt for Claude Code, Codex or other AI coding agent + +```text +I want to study galaxy structure and morphology with PyAutoGalaxy (https://github.com/PyAutoLabs/PyAutoGalaxy) +and the autogalaxy_assistant (https://github.com/PyAutoLabs/autogalaxy_assistant). First clone that +repository, cd into it and follow its AGENTS.md. + +Begin the "start here" guide for a new user. +``` + +The assistant takes you through the [Start Here](https://pyautogalaxy.readthedocs.io/en/latest/overview/overview_1_start_here.html) page as a conversation (grids, light profiles and bulge-plus-disk galaxies, then simulating and fitting a galaxy image), one step at a time, then +helps you get started on your own galaxies. Claude Code and Codex are recommended, and sustained scientific use +normally needs paid access to one of them. Free options are listed on the +[AI Options](https://github.com/PyAutoLabs/PyAutoScientist/blob/main/AI_OPTIONS.md) page. +[Start Here](https://pyautogalaxy.readthedocs.io/en/latest/overview/overview_1_start_here.html#natural-language-or-python) explains why **PyAutoGalaxy** is designed to be used in natural +language, and why its Python API is not going anywhere. + +### Documentation and Examples + +All of the documentation and examples are written for people to read: - [The PyAutoGalaxy readthedocs](https://pyautogalaxy.readthedocs.io/en/latest), which includes [an overview of PyAutoGalaxy's core features](https://pyautogalaxy.readthedocs.io/en/latest/overview/overview_1_start_here.html), [a new user starting guide](https://pyautogalaxy.readthedocs.io/en/latest/overview/overview_2_new_user_guide.html) and [an installation guide](https://pyautogalaxy.readthedocs.io/en/latest/installation/overview.html). - [The introduction Jupyter Notebook on Google Colab](https://colab.research.google.com/github/PyAutoLabs/autogalaxy_workspace/blob/2026.10.29.1/start_here.ipynb), where you can try **PyAutoGalaxy** in a web browser (without installation). - [The autogalaxy_workspace GitHub repository](https://github.com/PyAutoLabs/autogalaxy_workspace): example scripts covering every **PyAutoGalaxy** use case. - [The HowToGalaxy GitHub repository](https://github.com/PyAutoLabs/HowToGalaxy): a Jupyter notebook lecture series teaching galaxy modeling from the ground up. -### PyAutoGalaxy AI Assistant - -The [**PyAutoGalaxy AI Assistant**](https://github.com/PyAutoLabs/autogalaxy_assistant) lets you do galaxy structure and morphology science in natural language from inside an AI coding agent. You can get started simply by asking it a question about galaxy structure or describing the task you would like to perform with **PyAutoGalaxy**. See the assistant for its full scope and instructions. - -**The assistant runs inside an AI coding agent: Claude Code or Codex are recommended. Sustained scientific use normally needs paid access to one of them (a personal subscription, institutional access or API billing). OpenCode is an experimental alternative whose client is free but whose model access, cost and capability depend on the provider. Browser chat routes (ChatGPT or Claude with a GitHub connector) are no longer supported.** - ## Core Aims **PyAutoGalaxy** has three core aims: diff --git a/docs/_static/pyautogalaxy.css b/docs/_static/pyautogalaxy.css new file mode 100644 index 000000000..e71ef19aa --- /dev/null +++ b/docs/_static/pyautogalaxy.css @@ -0,0 +1,59 @@ +/* PyAutoGalaxy-only docs layer. The shared brand file `pyauto.css` is byte-identical + across PyAutoFit / PyAutoGalaxy / PyAutoLens, so repo-specific rules live here + instead of diverging it. The natural-language prompt block below is copied + from PyAutoFit's `pyautofit.css` so prompts look the same in all three docs. */ + +/* Natural-language prompt blocks. A prompt is written as a blockquote wrapped in + `:::{container} nl-prompt`, which gives it two things a plain blockquote has + not got: a label saying what the block is, and a copy button so the prompt can + be pasted straight into an AI coding agent. The label text lives here in + `content:` so every prompt on every overview page picks it up simply by being + wrapped in the same container — nothing is repeated in the Markdown. + + The container is the positioning context for the copy button, which + sphinx-copybutton inserts as a sibling of the blockquote (see + `copybutton_selector` in conf.py). */ +.nl-prompt { + position: relative; + margin: 1.2rem 0; +} + +.nl-prompt::before { + content: "Example Natural Language Prompt for Claude Code, Codex or other AI coding agent"; + display: block; + /* Keeps the label clear of the copy button when it wraps on narrow screens. */ + padding-right: 2.5rem; + margin-bottom: 0.35rem; + font-size: 0.7rem; + font-weight: 600; + letter-spacing: 0.06em; + text-transform: uppercase; + line-height: 1.4; + color: var(--color-foreground-muted); +} + +/* sphinx-copybutton's own stylesheet positions the button against `.highlight` + code blocks and hard-codes GitHub's light-mode colours; both are re-stated + here in Furo's theme variables so the button sits in the prompt container and + follows light/dark mode. Idle at low opacity (like a code block's button), + full opacity on hover or after a successful copy. */ +.nl-prompt button.copybtn { + position: absolute; + top: 0; + right: 0; + opacity: 0.35; + border: 1px solid var(--color-background-border); + background-color: var(--color-background-secondary); + color: var(--color-foreground-muted); +} + +.nl-prompt:hover button.copybtn, +.nl-prompt button.copybtn:focus-visible, +.nl-prompt button.copybtn.success { + opacity: 1; +} + +.nl-prompt button.copybtn:hover { + background-color: var(--color-background-hover); + color: var(--color-brand-content); +} diff --git a/docs/conf.py b/docs/conf.py index 1c8759c74..f6a1faff9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -75,6 +75,16 @@ todo_include_todos = True +# -- Options for copybutton -------------------------------------------------- + +# The default selector is "div.highlight pre" (code blocks only). The second +# entry adds the natural-language prompt blocks: any blockquote wrapped in a +# `:::{container} nl-prompt` aside gets its own copy button, so a reader can +# lift the prompt straight into an AI coding agent. The button is inserted as a +# sibling of the blockquote, inside the container, and copies the blockquote's +# innerText (the plain prompt, without the Markdown "> " markers). +copybutton_selector = "div.highlight pre, .nl-prompt blockquote" + # -- Options for Markdown files ---------------------------------------------- myst_enable_extensions = ["colon_fence", "deflist", "substitution"] @@ -128,7 +138,7 @@ language = "en" html_static_path = ["_static"] -html_css_files = ["pyauto.css"] +html_css_files = ["pyauto.css", "pyautogalaxy.css"] html_theme_options = { "light_css_variables": { diff --git a/docs/index.md b/docs/index.md index 4a9ad128b..c020a897f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -20,21 +20,37 @@ substitutions: # Getting Started -## Human-Readable Documentation and Examples +## Natural Language or Python -The following human-readable documentation and examples are useful for new starters: +You can use **PyAutoGalaxy** by describing what you want in natural language, through the +[**PyAutoGalaxy AI Assistant**](https://github.com/PyAutoLabs/autogalaxy_assistant), or by writing Python yourself. Both +routes use the same software. To start in natural language, paste this prompt into Claude Code, Codex or another AI +coding agent: + +:::{container} nl-prompt +> I want to study galaxy structure and morphology with PyAutoGalaxy (https://github.com/PyAutoLabs/PyAutoGalaxy) +> and the autogalaxy_assistant (https://github.com/PyAutoLabs/autogalaxy_assistant). First clone that +> repository, cd into it and follow its AGENTS.md. +> +> Begin the "start here" guide for a new user. +::: + +The assistant takes you through the [Start Here](https://pyautogalaxy.readthedocs.io/en/latest/overview/overview_1_start_here.html) page as a conversation (grids, light profiles and bulge-plus-disk galaxies, then simulating and fitting a galaxy image), one step at a time, then +helps you get started on your own galaxies. Claude Code and Codex are recommended, and sustained scientific use +normally needs paid access to one of them. Free options are listed on the +[AI Options](https://github.com/PyAutoLabs/PyAutoScientist/blob/main/AI_OPTIONS.md) page. +[Start Here](https://pyautogalaxy.readthedocs.io/en/latest/overview/overview_1_start_here.html#natural-language-or-python) explains why **PyAutoGalaxy** is designed to be used in natural +language, and why its Python API is not going anywhere. + +## Documentation and Examples + +All of the documentation and examples are written for people to read: - [The PyAutoGalaxy readthedocs](https://pyautogalaxy.readthedocs.io/en/latest/), which includes [an overview of PyAutoGalaxy's core features](https://pyautogalaxy.readthedocs.io/en/latest/overview/overview_1_start_here.html), [a new user starting guide](https://pyautogalaxy.readthedocs.io/en/latest/overview/overview_2_new_user_guide.html) and [an installation guide](https://pyautogalaxy.readthedocs.io/en/latest/installation/overview.html). - [The introduction Jupyter Notebook on Colab](https://colab.research.google.com/github/PyAutoLabs/autogalaxy_workspace/blob/2026.10.29.1/start_here.ipynb), where you can try **PyAutoGalaxy** in a web browser (without installation). - [The autogalaxy_workspace GitHub repository](https://github.com/PyAutoLabs/autogalaxy_workspace): example scripts covering every **PyAutoGalaxy** use case. - [The HowToGalaxy GitHub repository](https://github.com/PyAutoLabs/HowToGalaxy): a Jupyter notebook lecture series teaching galaxy modeling from the ground up. -## PyAutoGalaxy AI Assistant - -The [**PyAutoGalaxy AI Assistant**](https://github.com/PyAutoLabs/autogalaxy_assistant) lets you do galaxy structure and morphology science in natural language from inside an AI coding agent. You can get started simply by asking it a question about galaxy structure or describing the task you would like to perform with **PyAutoGalaxy**. See the assistant for its full scope and instructions. - -**The assistant runs inside an AI coding agent: Claude Code or Codex are recommended. Sustained scientific use normally needs paid access to one of them (a personal subscription, institutional access or API billing). OpenCode is an experimental alternative whose client is free but whose model access, cost and capability depend on the provider. Browser chat routes (ChatGPT or Claude with a GitHub connector) are no longer supported.** - # Core Aims **PyAutoGalaxy** has three core aims: diff --git a/docs/overview/overview_1_start_here.md b/docs/overview/overview_1_start_here.md index 4f16c36e6..3e7a51499 100644 --- a/docs/overview/overview_1_start_here.md +++ b/docs/overview/overview_1_start_here.md @@ -2,8 +2,6 @@ # Start Here -## Human-Readable Overview - **PyAutoGalaxy** is software for analysing the morphologies and structures of galaxies: ```{image} https://raw.githubusercontent.com/PyAutoLabs/PyAutoGalaxy/main/paper/hstcombined.png @@ -17,13 +15,44 @@ - **Model Complexity**: Fitting complex galaxy morphology models (e.g. Multi Gaussian Expansion, Shapelets, Ellipse Fitting, Irregular Meshes) that go beyond just simple Sérsic fitting. - **Data Variety**: Support for many data types (e.g. CCD imaging, interferometry, multi-band imaging) which can be fitted independently or simultaneously. -This overview gives an overview of **PyAutoGalaxy**'s API, core features and details of the autogalaxy_workspace. - -## PyAutoGalaxy AI Assistant - -The [**PyAutoGalaxy AI Assistant**](https://github.com/PyAutoLabs/autogalaxy_assistant) lets you do galaxy structure and morphology science in natural language from inside an AI coding agent. You can get started simply by asking it a question about galaxy structure or describing the task you would like to perform with **PyAutoGalaxy**. See the assistant for its full scope and instructions. - -**The assistant runs inside an AI coding agent: Claude Code or Codex are recommended. Sustained scientific use normally needs paid access to one of them (a personal subscription, institutional access or API billing). OpenCode is an experimental alternative whose client is free but whose model access, cost and capability depend on the provider. Browser chat routes (ChatGPT or Claude with a GitHub connector) are no longer supported.** +This page gives an overview of **PyAutoGalaxy**'s API, core features and details of the autogalaxy_workspace. + +## Natural Language or Python + +You can use **PyAutoGalaxy** by describing what you want in **natural language**, or by writing **Python** yourself. +Both routes use the same software and everything on this page can be done either way. + +To use natural language, open Claude Code, Codex or another AI coding agent and paste in the prompt below. The +[PyAutoGalaxy AI Assistant](https://github.com/PyAutoLabs/autogalaxy_assistant) then takes you through this page as a +conversation (grids, light profiles and bulge-plus-disk galaxies, then simulating and fitting a galaxy image), with you +typing each request in plain English. Afterwards it helps you get started on your own galaxies: + +:::{container} nl-prompt +> I want to study galaxy structure and morphology with PyAutoGalaxy (https://github.com/PyAutoLabs/PyAutoGalaxy) +> and the autogalaxy_assistant (https://github.com/PyAutoLabs/autogalaxy_assistant). First clone that +> repository, cd into it and follow its AGENTS.md. +> +> Begin the "start here" guide for a new user. +::: + +The assistant runs inside an AI coding agent. Claude Code and Codex are recommended, and sustained scientific use +normally needs paid access to one of them. Free options are listed on the +[AI Options](https://github.com/PyAutoLabs/PyAutoScientist/blob/main/AI_OPTIONS.md) page. + +**Why natural language?** Turning a scientific idea into an analysis has always meant expressing it through the syntax +of a programming language. That syntax was never the science: it is the interface between your ideas and the +computer. **PyAutoGalaxy** is designed so you can describe a galaxy analysis in the language you use to think and +write about it, while you supply the understanding, direction and judgement. The +[PyAuto AI Policy](https://github.com/PyAutoLabs/PyAutoScientist/blob/main/AI_POLICY.md) explains this approach in +more detail. + +**Python is not going anywhere.** Every **PyAutoGalaxy** feature remains available through its Python API, and the +assistant writes ordinary **PyAutoGalaxy** code that you can read, run and change. All the documentation is written +for people to read. The rest of this page is the Python overview, the +[autogalaxy_workspace](https://github.com/PyAutoLabs/autogalaxy_workspace) holds runnable examples for every use case, +and the [HowToGalaxy](https://github.com/PyAutoLabs/HowToGalaxy) lectures teach galaxy structure and galaxy modeling +from first principles. That understanding is what lets you direct an analysis with expertise, whether you do it in +natural language or in Python. ## Imports diff --git a/docs/overview/overview_2_new_user_guide.md b/docs/overview/overview_2_new_user_guide.md index 2a475fd6a..fce35ec64 100644 --- a/docs/overview/overview_2_new_user_guide.md +++ b/docs/overview/overview_2_new_user_guide.md @@ -2,20 +2,17 @@ # New User Guide -## Human-Readable Guide - **PyAutoGalaxy** can analyse galaxies for different types of data (e.g. CCD imaging and interferometer observations) and across a range of system scales (a single galaxy, blended multi-galaxy systems, and cluster fields). Depending on the data you use and the scale of your system, the analysis you perform may differ significantly. The autogalaxy_workspace contains a suite of example Jupyter Notebooks, organised by dataset type and system scale. -To help you find the most appropriate starting point, answer two simple questions: - -## PyAutoGalaxy AI Assistant - -The [**PyAutoGalaxy AI Assistant**](https://github.com/PyAutoLabs/autogalaxy_assistant) lets you do galaxy structure and morphology science in natural language from inside an AI coding agent. You can get started simply by asking it a question about galaxy structure or describing the task you would like to perform with **PyAutoGalaxy**. See the assistant for its full scope and instructions. +To help you find the most appropriate starting point, answer two simple questions. -**The assistant runs inside an AI coding agent: Claude Code or Codex are recommended. Sustained scientific use normally needs paid access to one of them (a personal subscription, institutional access or API billing). OpenCode is an experimental alternative whose client is free but whose model access, cost and capability depend on the provider. Browser chat routes (ChatGPT or Claude with a GitHub connector) are no longer supported.** +**In natural language:** if you are using the [PyAutoGalaxy AI Assistant](https://github.com/PyAutoLabs/autogalaxy_assistant), you can skip +the questions below: describe your galaxies and your data type to the assistant and it will pick the matching +example and work through it with you. The examples below are what the assistant uses, and they remain the best place +to see the Python. ## What Scale System?