Added doctools.py utility script (haddocking#47)

* Added utility script to produce tool documentation.

* Fixed whitespace bc of Flake8

* Leave the bad script alone.

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('<', '&lt').replace('>', '&gt')
+		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("<div>")
+		print('<details>')
+		print(f"<summary><b>{name}</b><p>{summary}</p></summary>")
+		print(f'<span style="font-family: monospace; white-space: pre;">{long_description}</span>')
+		print('</details>')
+		print('</div>')
+
+

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.
 

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

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.
 

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.
 

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.

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`.

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:

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

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.
 

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'.

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
+commands = codecov -e TOXENV