Repository navigation
Add the Sphinx documentation with figures, logo and favicon - #141
Open
David-Araripe wants to merge 42 commits into
Open
David-Araripe wants to merge 42 commits into
David-Araripe wants to merge 42 commits into
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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/)Figures (
docs/source/_static/figures/, scripts indocs/scripts/)docs/source/_ext/themed_figures.pypairs<name>-light.svgwith<name>-dark.svg, so a page has one figure directive and one caption.docs/scripts/data/.Logo and favicon
docs/source/_static/q-logo.svgabove the sidebar andq-favicon.pngin the tab, both built bydocs/scripts/logo/make_logo.sh.Two commits that are not documentation
refactor(qligfep): remove OPLS2015 in favour of OPLSAAM: removesOPLS2015.lib/.prmand theOPLS2015choice from the CLI. The foldersrc/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, whichqdynignores. Behaviour is unchanged because both keywords were at their defaults.Notes for review
concepts/softcore.md, with its three figures, describesfeature/softcore-charge-changing, which is not merged. It is marked with a warning box.dev. It merges without conflicts.Testing
sphinx-build -W --keep-going -b html docs/source docs/build/htmlpasses on the branch and on a trial merge withdev.dev:test_io.py,test_qprep_cli.py,test_qresfep.pyandtest_templates.py, 322 passed. These are the test files touched by the two non-documentation commits.test_io.py::test_parse_real_qprep_outfails because it reads an untracked file; Read Tyk2 test inputs from the tracked resources #138 ondevfixed that.