Merge pull request #420 from rbberger/doc_anchor_check

Add utility to detect duplicate anchors in docs

doc/Makefile

@@ -22,7 +22,7 @@ endif
 SOURCES=$(wildcard src/*.txt)
 OBJECTS=$(SOURCES:src/%.txt=$(RSTDIR)/%.rst)
 
-.PHONY: help clean-all clean epub html pdf old venv spelling
+.PHONY: help clean-all clean epub html pdf old venv spelling anchor_check
 
 # ------------------------------------------
 
@@ -36,6 +36,7 @@ help:
 	@echo "  clean      remove all intermediate RST files"
 	@echo "  clean-all  reset the entire build environment"
 	@echo "  txt2html   build txt2html tool"
+	@echo "  anchor_check  scan for duplicate anchor labels"
 
 # ------------------------------------------
 
@@ -54,6 +55,9 @@ html: $(OBJECTS)
 		. $(VENV)/bin/activate ;\
 		cp -r src/* $(RSTDIR)/ ;\
 		sphinx-build -j 8 -b html -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) html ;\
+		echo "############################################" ;\
+		doc_anchor_check src/*.txt ;\
+		echo "############################################" ;\
 		deactivate ;\
 	)
 	-rm html/searchindex.js
@@ -127,6 +131,13 @@ fetch:
 
 txt2html: utils/txt2html/txt2html.exe
 
+anchor_check : $(TXT2RST)
+	@(\
+		. $(VENV)/bin/activate ;\
+		doc_anchor_check src/*.txt ;\
+		deactivate ;\
+	)
+
 # ------------------------------------------
 
 utils/txt2html/txt2html.exe: utils/txt2html/txt2html.cpp

doc/src/fix_qeq_reax.txt

@@ -36,7 +36,7 @@ uses charges on each atom.  The "fix qeq/comb"_fix_qeq_comb.html
 command should be used to perform charge equilibration with the "COMB
 potential"_pair_comb.html.  For more technical details about the
 charge equilibration performed by fix qeq/reax, see the
-"(Aktulga)"_#Aktulga paper.
+"(Aktulga)"_#qeq-Aktulga paper.
 
 The QEq method minimizes the electrostatic energy of the system by
 adjusting the partial charge on individual atoms based on interactions
@@ -119,6 +119,6 @@ be used for periodic cell dimensions less than 10 angstroms.
 :link(Nakano)
 [(Nakano)] Nakano, Computer Physics Communications, 104, 59-69 (1997).
 
-:link(Aktulga)
-(Aktulga) Aktulga, Fogarty, Pandit, Grama, Parallel Computing, 38,
+:link(qeq-Aktulga)
+[(Aktulga)] Aktulga, Fogarty, Pandit, Grama, Parallel Computing, 38,
 245-259 (2012).

doc/src/pair_polymorphic.txt

@@ -52,7 +52,7 @@ to Stillinger-Weber potential ("SW"_#SW) if we set
 :c,image(Eqs/polymorphic4.jpg)
 
 The potential reduces to Tersoff types of potential
-("Tersoff"_#Tersoff or "Albe"_#Albe) if we set
+("Tersoff"_#Tersoff or "Albe"_#poly-Albe) if we set
 
 :c,image(Eqs/polymorphic5.jpg)
 :c,image(Eqs/polymorphic6.jpg)
@@ -63,7 +63,7 @@ The potential reduces to Rockett-Tersoff ("Wang"_#Wang) type if we set
 :c,image(Eqs/polymorphic6.jpg)
 :c,image(Eqs/polymorphic8.jpg)
 
-The potential becomes embedded atom method ("Daw"_#Daw) if we set
+The potential becomes embedded atom method ("Daw"_#poly-Daw) if we set
 
 :c,image(Eqs/polymorphic9.jpg)
 
@@ -218,12 +218,12 @@ F. P. Doty, J. Mater. Sci. Res., 4, 15 (2015).
 :link(Tersoff)
 [(Tersoff)] J. Tersoff, Phys. Rev. B, 39, 5566 (1989).
 
-:link(Albe)
+:link(poly-Albe)
 [(Albe)] K. Albe, K. Nordlund, J. Nord, and A. Kuronen, Phys. Rev. B,
 66, 035205 (2002).
 
 :link(Wang)
 [(Wang)] J. Wang, and A. Rockett, Phys. Rev. B, 43, 12571 (1991).
 
-:link(Daw)
+:link(poly-Daw)
 [(Daw)] M. S. Daw, and M. I. Baskes, Phys. Rev. B, 29, 6443 (1984).

doc/src/pair_tersoff_zbl.txt

@@ -23,9 +23,9 @@ pair_coeff * * SiC.tersoff.zbl Si C Si :pre
 [Description:]
 
 The {tersoff/zbl} style computes a 3-body Tersoff potential
-"(Tersoff_1)"_#Tersoff_1 with a close-separation pairwise modification
+"(Tersoff_1)"_#zbl-Tersoff_1 with a close-separation pairwise modification
 based on a Coulomb potential and the Ziegler-Biersack-Littmark
-universal screening function "(ZBL)"_#ZBL, giving the energy E of a
+universal screening function "(ZBL)"_#zbl-ZBL, giving the energy E of a
 system of atoms as
 
 :c,image(Eqs/pair_tersoff_zbl.jpg)
@@ -146,16 +146,16 @@ be set to 0.0 if desired.
 Note that the twobody parameters in entries such as SiCC and CSiSi
 are often the same, due to the common use of symmetric mixing rules,
 but this is not always the case. For example, the beta and n parameters in
-Tersoff_2 "(Tersoff_2)"_#Tersoff_2 are not symmetric.
+Tersoff_2 "(Tersoff_2)"_#zbl-Tersoff_2 are not symmetric.
 
 We chose the above form so as to enable users to define all commonly
 used variants of the Tersoff portion of the potential.  In particular,
 our form reduces to the original Tersoff form when m = 3 and gamma =
-1, while it reduces to the form of "Albe et al."_#Albe when beta = 1
+1, while it reduces to the form of "Albe et al."_#zbl-Albe when beta = 1
 and m = 1.  Note that in the current Tersoff implementation in LAMMPS,
 m must be specified as either 3 or 1.  Tersoff used a slightly
 different but equivalent form for alloys, which we will refer to as
-Tersoff_2 potential "(Tersoff_2)"_#Tersoff_2.
+Tersoff_2 potential "(Tersoff_2)"_#zbl-Tersoff_2.
 
 LAMMPS parameter values for Tersoff_2 can be obtained as follows:
 gamma = omega_ijk, lambda3 = 0 and the value of
@@ -253,16 +253,16 @@ units.
 
 :line
 
-:link(Tersoff_1)
+:link(zbl-Tersoff_1)
 [(Tersoff_1)] J. Tersoff, Phys Rev B, 37, 6991 (1988).
 
-:link(ZBL)
+:link(zbl-ZBL)
 [(ZBL)] J.F. Ziegler, J.P. Biersack, U. Littmark, 'Stopping and Ranges
 of Ions in Matter' Vol 1, 1985, Pergamon Press.
 
-:link(Albe)
+:link(zbl-Albe)
 [(Albe)] J. Nord, K. Albe, P. Erhart and K. Nordlund, J. Phys.:
 Condens. Matter, 15, 5649(2003).
 
-:link(Tersoff_2)
+:link(zbl-Tersoff_2)
 [(Tersoff_2)] J. Tersoff, Phys Rev B, 39, 5566 (1989); errata (PRB 41, 3248)

doc/utils/converters/lammpsdoc/doc_anchor_check.py

+#! /usr/bin/env python3
+# LAMMPS Documentation Utilities
+#
+# Scan for duplicate anchor labels in documentation files
+#
+# Copyright (C) 2017 Richard Berger
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+import re
+import sys
+import argparse
+
+def main():
+    parser = argparse.ArgumentParser(description='scan for duplicate anchor labels in documentation files')
+    parser.add_argument('files',  metavar='file', nargs='+', help='one or more files to scan')
+    parsed_args = parser.parse_args()
+
+    anchor_pattern = re.compile(r'^:link\(([^,\)]*)\)')
+    anchors = {}
+
+    for filename in parsed_args.files:
+        with open(filename, 'rt') as f:
+            for line_number, line in enumerate(f):
+                m = anchor_pattern.match(line)
+                if m:
+                    label = m.group(1)
+                    if label in anchors:
+                        anchors[label].append((filename, line_number+1))
+                    else:
+                        anchors[label] = [(filename, line_number+1)]
+
+    count = 0
+
+    for label in sorted(anchors.keys()):
+        if len(anchors[label]) > 1:
+            print(label)
+            count += 1
+            for filename, line_number in anchors[label]:
+                print(" - %s:%d" % (filename, line_number))
+
+
+    if count > 0:
+        print("Found %d anchor label errors." % count)
+        sys.exit(1)
+    else:
+        print("No anchor label errors.")
+
+if __name__ == "__main__":
+    main()

doc/utils/converters/setup.py

@@ -12,6 +12,7 @@ setup(name='LAMMPS Documentation Utilities',
       tests_require=['nose'],
       entry_points = {
           "console_scripts": ['txt2html = lammpsdoc.txt2html:main',
-                              'txt2rst  = lammpsdoc.txt2rst:main']
+                              'txt2rst  = lammpsdoc.txt2rst:main',
+                              'doc_anchor_check = lammpsdoc.doc_anchor_check:main ']
       },
 )