diff --git a/docs/doctools.py b/docs/doctools.py new file mode 100644 index 00000000..fd894f68 --- /dev/null +++ b/docs/doctools.py @@ -0,0 +1,53 @@ +#!/usr/bin/env python + +""" +Scrapes tool headers for documentation. +""" + +import importlib +from pathlib import Path + +with open('descriptions.md', 'w') as handle: + + import pdbtools + modfile = Path(pdbtools.__file__) + for f in modfile.parent.iterdir(): + # ignore __init__.py and others. + if f.stem.startswith('_') or f.suffix != '.py': + continue + + # Dynamically import tool to get __doc__ + name = f.stem + try: + tool = importlib.import_module(f'pdbtools.{name}') + except ModuleNotFoundError: + print(f'Could not import module: {name}') + continue + + # Parse documentation from docstrings + # Preserve white-space as best as possible. + # First non-empty line is always short description. + # Last lines are always licensing disclaimer + summary = None + long_description = [] + + doctext = tool.__doc__.replace('<', '<').replace('>', '>') + for line in doctext.split('\n'): + if summary is None and not line.strip(): + continue + if line.startswith('This program is part of the'): + break + elif summary is None: + summary = line + else: + long_description.append(line) + + long_description = '\n'.join(long_description) + print("
") + print('
') + print(f"{name}

{summary}

") + print(f'{long_description}') + print('
') + print('
') + + diff --git a/pdbtools/pdb_delelem.py b/pdbtools/pdb_delelem.py index bd116b85..66930dd0 100644 --- a/pdbtools/pdb_delelem.py +++ b/pdbtools/pdb_delelem.py @@ -16,7 +16,7 @@ # limitations under the License. """ -Deletes all atoms matching the given element in the PDB file. +Deletes all atoms matching the given element in the PDB file. Elements are read from the element column. diff --git a/pdbtools/pdb_delres.py b/pdbtools/pdb_delres.py index 51705031..754a848b 100644 --- a/pdbtools/pdb_delres.py +++ b/pdbtools/pdb_delres.py @@ -16,7 +16,7 @@ # limitations under the License. """ -Deletes a range of residues from a PDB file. +Deletes a range of residues from a PDB file. The range option has three components: start, end, and step. Start and end are optional and if ommitted the range will start at the first residue or diff --git a/pdbtools/pdb_delresname.py b/pdbtools/pdb_delresname.py index 226d51de..31c64d93 100644 --- a/pdbtools/pdb_delresname.py +++ b/pdbtools/pdb_delresname.py @@ -16,7 +16,7 @@ # limitations under the License. """ -Removes all residues matching the given name in the PDB file. +Removes all residues matching the given name in the PDB file. Residues names are matched *without* taking into consideration spaces. diff --git a/pdbtools/pdb_fetch.py b/pdbtools/pdb_fetch.py index 6654779e..41d5f3d3 100644 --- a/pdbtools/pdb_fetch.py +++ b/pdbtools/pdb_fetch.py @@ -16,7 +16,7 @@ # limitations under the License. """ -Downloads a structure in PDB format from the RCSB website. +Downloads a structure in PDB format from the RCSB website. Allows downloading the (first) biological structure if selected. diff --git a/pdbtools/pdb_fromcif.py b/pdbtools/pdb_fromcif.py index c323a07e..c1668095 100644 --- a/pdbtools/pdb_fromcif.py +++ b/pdbtools/pdb_fromcif.py @@ -16,7 +16,7 @@ # limitations under the License. """ -Rudimentarily converts a mmCIF file to the PDB format. +Rudimentarily converts a mmCIF file to the PDB format. Will not convert if the file does not 'fit' in PDB format, e.g. too many chains, residues, or atoms. Will convert only the coordinate section. diff --git a/pdbtools/pdb_merge.py b/pdbtools/pdb_merge.py index 765aee7f..278d51a3 100644 --- a/pdbtools/pdb_merge.py +++ b/pdbtools/pdb_merge.py @@ -16,7 +16,7 @@ # limitations under the License. """ -Merges several PDB files into one. +Merges several PDB files into one. The contents are not sorted and no lines are deleted (e.g. END, TER statements) so we recommend piping the results through `pdb_tidy.py`. diff --git a/pdbtools/pdb_selaltloc.py b/pdbtools/pdb_selaltloc.py index c7e0234a..03f400e4 100644 --- a/pdbtools/pdb_selaltloc.py +++ b/pdbtools/pdb_selaltloc.py @@ -18,7 +18,7 @@ """ Selects altloc labels for the entire PDB file. -By default, picks the label with the highest occupancy value for each atom, +By default, picks the label with the highest occupancy value for each atom, but the user can define a specific label. Removes all labels afterwards. Usage: diff --git a/pdbtools/pdb_selres.py b/pdbtools/pdb_selres.py index d8461618..aeaddef7 100644 --- a/pdbtools/pdb_selres.py +++ b/pdbtools/pdb_selres.py @@ -16,7 +16,7 @@ # limitations under the License. """ -Selects residues by their index, piecewise or in a range. +Selects residues by their index, piecewise or in a range. The range option has three components: start, end, and step. Start and end are optional and if ommitted the range will start at the first residue or diff --git a/pdbtools/pdb_tocif.py b/pdbtools/pdb_tocif.py index 9a818a28..718f307e 100644 --- a/pdbtools/pdb_tocif.py +++ b/pdbtools/pdb_tocif.py @@ -16,7 +16,7 @@ # limitations under the License. """ -Rudimentarily converts the PDB file to mmCIF format. +Rudimentarily converts the PDB file to mmCIF format. Will convert only the coordinate section. diff --git a/pdbtools/pdb_tofasta.py b/pdbtools/pdb_tofasta.py index 83c3ae50..18bbfb25 100644 --- a/pdbtools/pdb_tofasta.py +++ b/pdbtools/pdb_tofasta.py @@ -16,7 +16,7 @@ # limitations under the License. """ -Extracts the residue sequence in a PDB file to FASTA format. +Extracts the residue sequence in a PDB file to FASTA format. Canonical amino acids and nucleotides are represented by their one-letter code while all others are represented by 'X'. diff --git a/tox.ini b/tox.ini index 374b199e..bc0cdacb 100644 --- a/tox.ini +++ b/tox.ini @@ -2,6 +2,7 @@ exclude = .git, .github, + docs/, pdbtools/__pycache__, tests/, setup.py @@ -15,4 +16,4 @@ statistics = True [testenv] passenv = TOXENV CI TRAVIS TRAVIS_* deps = codecov>=1.4.0 -commands = codecov -e TOXENV \ No newline at end of file +commands = codecov -e TOXENV