Skip to content

Add the Sphinx documentation with figures, logo and favicon - #141

Open
David-Araripe wants to merge 42 commits into
devfrom
feature/documentation
Open

David-Araripe wants to merge 42 commits into
devfrom
feature/documentation

Conversation

@David-Araripe

Copy link
Copy Markdown
Collaborator

What this changes

Adds the Sphinx documentation (MyST, Furo, Read the Docs config) under docs/, with its figures and the scripts that generate them.

Pages (43 Markdown files in docs/source/)

  • Getting started, QligFEP workflow, CLI reference, Tyk2 tutorial, troubleshooting.
  • Concepts: how Q does FEP, soft-core and the endpoint problem, the spherical boundary, electrostatics in the sphere.
  • The Q manual, ported from the 2017 manual as one page per chapter and aligned with the current source.

Figures (docs/source/_static/figures/, scripts in docs/scripts/)

  • 11 plots as SVG, each in a light and a dark variant, and 3 molecular renders as PNG with a transparent background.
  • docs/source/_ext/themed_figures.py pairs <name>-light.svg with <name>-dark.svg, so a page has one figure directive and one caption.
  • Scripts that need structures or data outside the repository take the paths as arguments; nothing large is committed. The BAR-overlap figure is drawn from a 6 kB summary in docs/scripts/data/.

Logo and favicon

  • docs/source/_static/q-logo.svg above the sidebar and q-favicon.png in the tab, both built by docs/scripts/logo/make_logo.sh.

Two commits that are not documentation

  • refactor(qligfep): remove OPLS2015 in favour of OPLSAAM: removes OPLS2015.lib/.prm and the OPLS2015 choice from the CLI. The folder src/QligFEP/FF/.FEP/OPLS2015/ is not touched and is still in the tree.
  • fix(qligfep): spell polarization keywords as qdyn reads them: the legacy input templates, the defaults and the test runner used the British spelling, which qdyn ignores. Behaviour is unchanged because both keywords were at their defaults.

Notes for review

  • The section "Weight-dependent soft-core (in development)" in concepts/softcore.md, with its three figures, describes feature/softcore-charge-changing, which is not merged. It is marked with a warning box.
  • The sphere-vs-box figure uses an A2A membrane system; its caption says the membrane tools are not public yet.
  • Three figure to-do comments remain in the concept pages (they need trajectories).
  • The branch started before the last 36 commits on dev. It merges without conflicts.

Testing

  • sphinx-build -W --keep-going -b html docs/source docs/build/html passes on the branch and on a trial merge with dev.
  • On the trial merge with dev: test_io.py, test_qprep_cli.py, test_qresfep.py and test_templates.py, 322 passed. These are the test files touched by the two non-documentation commits.
  • On the branch alone, test_io.py::test_parse_real_qprep_out fails because it reads an untracked file; Read Tyk2 test inputs from the tracked resources #138 on dev fixed that.
  • The full test suite was not run.

Baseline of the existing draft pages (Sphinx, MyST, Furo, Read the Docs config). The condensed engine manual is inlined as docs/source/q-engine/manual.md instead of being included from the untracked q-manual directory.
Add concept pages on the mapping potential, energy-file bookkeeping and qfep's linear reconstruction, and on why the default soft-core has no effect in QligFEP dual-topology input and where the endpoint problem comes from.
Replace the single condensed manual page with one page per chapter of the 2017 Manual for Q6: introduction, topology preparation, running qdyn, FEP files, analysis with qfep, scoring and the LIE tutorial. Program names and keywords follow this source.
Add reference pages for force fields, qprep, the library, parameter, qdyn input and FEP file formats, boundary conditions, algorithms and utilities, checked against the keywords read by this source. List the differences from, and corrections to, the 2017 manual.
qdyn reads polarization and polarization_force and ignores unknown keys, so the British spelling in the legacy input templates, the default settings and the test runner had no effect. Behaviour is unchanged because both keywords were at their defaults.
Check commands, keywords, columns and defaults against qatom.f90, md.f90, prep.f90, mask.f90 and qfep.f90, and correct the pages: per-state el_scale, four-type impropers, Urey-Bradley columns, improper coupling flag, qprep boundary/solvate/writepdb/writemol2 arguments, mask keywords and the qfep input. Remove Q6 features that this source does not have, use library and parameter examples from the shipped force fields, and fold the q-engine quick guides into the manual.
Add concept pages on the simulation sphere (regions, radial and polarisation restraints, Born shift of the surface polarisation) and on electrostatics (charge groups, Q-atom cut-off, local reaction field, the implicit outside continuum, boundary neutralisation and charge-changing edges). Figures are left as detailed to-do comments.
Name the dynamics/bookkeeping distinction on the FEP concept page, add figure to-do comments, and bring the boundary reference page in line with the source (fractional shell radius, charge-group assignment, Q-atom charge in the Born shift, adaptive polarisation offsets).
Take the library and parameter examples from AMBER14sb, list OPLSAAM as the OPLS-AA/M force field, and refer to the old manual as the 2017 Q manual. Explain that shell_radius restrains solute inside the sphere without shrinking it, state which charge enters the polarisation target, and replace the 'legs must match' rule by the state difference of the Born term, which vanishes for equally charged ligands.
Delete the OPLS2015 library and parameter files and replace the name by OPLSAAM in the water and chloride type tables, the bundled force-field list, CLI help, opls2Q, QLIE and the legacy scripts. Tests that used OPLS2015 now use OPLSAAM or OPLS2005; the test of the fractional neutral C-terminal arginine template is removed because only OPLS2015 had that template. The Tyk2 tutorial drops its OPLS2015 section and the CCR2 tutorial uses OPLSAAM.
Adds a shared figure style that writes light and dark SVG variants, and a small Sphinx extension that pairs them so a page needs one figure directive and one caption.
The title now states what is plotted. The weights and the plotted pair are unchanged.
Adds a section, marked as in development, on the weight-dependent soft-core of the unmerged feature/softcore-charge-changing branch. The plotted values match the compiled qsoftcore.f90 module.
The figure is drawn from a 6 kB per-step summary kept next to the script; the dashboard data it is built from stays outside the repository.
Uses a thinner slab perpendicular to y, draws water as sticks with red oxygen and white hydrogens, wraps the excluded residues in a translucent surface, and drops the centre mark.
Replaces the backbone trace with a whole-protein cartoon and a surface over the excluded atoms, and draws the ionisable side chains of a 12 A slab. The render script was drafted with Codex and is kept in docs/scripts.
The logo is built by docs/scripts/logo/make_logo.sh from tracked test inputs.
Remove the comparison with the 2017 manual and number the bibliography sequentially. The differences page is excluded from the build until the file is deleted.
…ng page

State that the documented engine is the CPU implementation and that Q-GPU is under development. Hide the site name next to the sidebar logo.
The Linux, macOS and PyMOL instructions are now included from marked blocks of the README, so the two cannot diverge.
The script names are kept as Markdown comments after each figure.
Replace the Tyk2 page with one page that links to the Tyk2, NEQ, CCR2 and T4 lysozyme tutorials. The quickstart and T4 lysozyme pages are excluded from the build until the files are deleted.
Add qprep_prot --strip-crystal-waters and qligfep_analyze --qc, and correct the default handling of crystallographic waters.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant