From e7cdb20895d492193acdbdf0342aad096e19ae4f Mon Sep 17 00:00:00 2001 From: Martin Vseticka Date: Wed, 1 Feb 2017 14:44:47 +0100 Subject: [PATCH] Update documentation.py Hopefully fixes/improves #21 issue. I have used the following repo: https://github.com/Reference-LAPACK/lapack as the data source, I'm not sure if it is a correct one though. However, it should be documented somewhere. :-) I ran: ``` python3 c.py ../.data/lapack-master >new.result ``` and I got the following diff: ``` 27,29c27,30 < /// Returns D.P. Dot product accumulated in D.P., for S.P. SX and SY DSDOT = sum < /// for I = 0 to N-1 of SX(LX+I*INCX) * SY(LY+I*INCY), where LX = 1 if INCX .GE. < /// 0, else LX = 1+(1-N)*INCX, and LY is defined in a similar way using INCY. --- > /// Returns D.P. dot product accumulated in D.P., for S.P. SX and SY > /// DSDOT = sum for I = 0 to N-1 of SX(LX+I*INCX) * SY(LY+I*INCY), > /// where LX = 1 if INCX .GE. 0, else LX = 1+(1-N)*INCX, and LY is > /// defined in a similar way using INCY. 312,321c313,324 < /// CONSTRUCT THE MODIFIED GIVENS TRANSFORMATION MATRIX H WHICH ZEROS THE SECOND < /// COMPONENT OF THE 2-VECTOR (SQRT(SD1)*SX1,SQRT(SD2)*> SY2)**T. WITH < /// SPARAM(1)=SFLAG, H HAS ONE OF THE FOLLOWING FORMS.. < /// < /// SFLAG=-1.E0 SFLAG=0.E0 SFLAG=1.E0 SFLAG=-2.E0 < /// < /// (SH11 SH12) (1.E0 SH12) (SH11 1.E0) (1.E0 0.E0) H=() () () () (SH21 SH22), < /// (SH21 1.E0), (-1.E0 SH22), (0.E0 1.E0). LOCATIONS 2-4 OF SPARAM CONTAIN < /// SH11,SH21,SH12, AND SH22 RESPECTIVELY. (VALUES OF 1.E0, -1.E0, OR 0.E0 < /// IMPLIED BY THE VALUE OF SPARAM(1) ARE NOT STORED IN SPARAM.) --- > /// CONSTRUCT THE MODIFIED GIVENS TRANSFORMATION MATRIX H WHICH ZEROS > /// THE SECOND COMPONENT OF THE 2-VECTOR (SQRT(SD1)*SX1,SQRT(SD2)*> SY2)**T. > /// WITH SPARAM(1)=SFLAG, H HAS ONE OF THE FOLLOWING FORMS.. > /// > /// SFLAG=-1.E0 SFLAG=0.E0 SFLAG=1.E0 SFLAG=-2.E0 > /// > /// (SH11 SH12) (1.E0 SH12) (SH11 1.E0) (1.E0 0.E0) > /// H=( ) ( ) ( ) ( ) > /// (SH21 SH22), (SH21 1.E0), (-1.E0 SH22), (0.E0 1.E0). > /// LOCATIONS 2-4 OF SPARAM CONTAIN SH11,SH21,SH12, AND SH22 > /// RESPECTIVELY. (VALUES OF 1.E0, -1.E0, OR 0.E0 IMPLIED BY THE > /// VALUE OF SPARAM(1) ARE NOT STORED IN SPARAM.) 345,353c348,357 < /// SX(LX+I*INCX), I = 0 TO N-1, WHERE LX = 1 IF INCX .GE. 0, ELSE LX = < /// (-INCX)*N, AND SIMILARLY FOR SY USING USING LY AND INCY. WITH < /// SPARAM(1)=SFLAG, H HAS ONE OF THE FOLLOWING FORMS.. < /// < /// SFLAG=-1.E0 SFLAG=0.E0 SFLAG=1.E0 SFLAG=-2.E0 < /// < /// (SH11 SH12) (1.E0 SH12) (SH11 1.E0) (1.E0 0.E0) H=() () () () (SH21 SH22), < /// (SH21 1.E0), (-1.E0 SH22), (0.E0 1.E0). SEE SROTMG FOR A DESCRIPTION OF DATA < /// STORAGE IN SPARAM. --- > /// SX(LX+I*INCX), I = 0 TO N-1, WHERE LX = 1 IF INCX .GE. 0, ELSE > /// LX = (-INCX)*N, AND SIMILARLY FOR SY USING USING LY AND INCY. > /// WITH SPARAM(1)=SFLAG, H HAS ONE OF THE FOLLOWING FORMS.. > /// > /// SFLAG=-1.E0 SFLAG=0.E0 SFLAG=1.E0 SFLAG=-2.E0 > /// > /// (SH11 SH12) (1.E0 SH12) (SH11 1.E0) (1.E0 0.E0) > /// H=( ) ( ) ( ) ( ) > /// (SH21 SH22), (SH21 1.E0), (-1.E0 SH22), (0.E0 1.E0). > /// SEE SROTMG FOR A DESCRIPTION OF DATA STORAGE IN SPARAM. 369,378c373,384 < /// CONSTRUCT THE MODIFIED GIVENS TRANSFORMATION MATRIX H WHICH ZEROS THE SECOND < /// COMPONENT OF THE 2-VECTOR (DSQRT(DD1)*DX1,DSQRT(DD2)*> DY2)**T. WITH < /// DPARAM(1)=DFLAG, H HAS ONE OF THE FOLLOWING FORMS.. < /// < /// DFLAG=-1.D0 DFLAG=0.D0 DFLAG=1.D0 DFLAG=-2.D0 < /// < /// (DH11 DH12) (1.D0 DH12) (DH11 1.D0) (1.D0 0.D0) H=() () () () (DH21 DH22), < /// (DH21 1.D0), (-1.D0 DH22), (0.D0 1.D0). LOCATIONS 2-4 OF DPARAM CONTAIN < /// DH11, DH21, DH12, AND DH22 RESPECTIVELY. (VALUES OF 1.D0, -1.D0, OR 0.D0 < /// IMPLIED BY THE VALUE OF DPARAM(1) ARE NOT STORED IN DPARAM.) --- > /// CONSTRUCT THE MODIFIED GIVENS TRANSFORMATION MATRIX H WHICH ZEROS > /// THE SECOND COMPONENT OF THE 2-VECTOR (DSQRT(DD1)*DX1,DSQRT(DD2)*> DY2)**T. > /// WITH DPARAM(1)=DFLAG, H HAS ONE OF THE FOLLOWING FORMS.. > /// > /// DFLAG=-1.D0 DFLAG=0.D0 DFLAG=1.D0 DFLAG=-2.D0 > /// > /// (DH11 DH12) (1.D0 DH12) (DH11 1.D0) (1.D0 0.D0) > /// H=( ) ( ) ( ) ( ) > /// (DH21 DH22), (DH21 1.D0), (-1.D0 DH22), (0.D0 1.D0). > /// LOCATIONS 2-4 OF DPARAM CONTAIN DH11, DH21, DH12, AND DH22 > /// RESPECTIVELY. (VALUES OF 1.D0, -1.D0, OR 0.D0 IMPLIED BY THE > /// VALUE OF DPARAM(1) ARE NOT STORED IN DPARAM.) 402,410c408,417 < /// DX(LX+I*INCX), I = 0 TO N-1, WHERE LX = 1 IF INCX .GE. 0, ELSE LX = < /// (-INCX)*N, AND SIMILARLY FOR SY USING LY AND INCY. WITH DPARAM(1)=DFLAG, H < /// HAS ONE OF THE FOLLOWING FORMS.. < /// < /// DFLAG=-1.D0 DFLAG=0.D0 DFLAG=1.D0 DFLAG=-2.D0 < /// < /// (DH11 DH12) (1.D0 DH12) (DH11 1.D0) (1.D0 0.D0) H=() () () () (DH21 DH22), < /// (DH21 1.D0), (-1.D0 DH22), (0.D0 1.D0). SEE DROTMG FOR A DESCRIPTION OF DATA < /// STORAGE IN DPARAM. --- > /// DX(LX+I*INCX), I = 0 TO N-1, WHERE LX = 1 IF INCX .GE. 0, ELSE > /// LX = (-INCX)*N, AND SIMILARLY FOR SY USING LY AND INCY. > /// WITH DPARAM(1)=DFLAG, H HAS ONE OF THE FOLLOWING FORMS.. > /// > /// DFLAG=-1.D0 DFLAG=0.D0 DFLAG=1.D0 DFLAG=-2.D0 > /// > /// (DH11 DH12) (1.D0 DH12) (DH11 1.D0) (1.D0 0.D0) > /// H=( ) ( ) ( ) ( ) > /// (DH21 DH22), (DH21 1.D0), (-1.D0 DH22), (0.D0 1.D0). > /// SEE DROTMG FOR A DESCRIPTION OF DATA STORAGE IN DPARAM. ``` --- bin/documentation.py | 78 ++++++++++++++++++++++++++------------------ 1 file changed, 46 insertions(+), 32 deletions(-) diff --git a/bin/documentation.py b/bin/documentation.py index b4ebaf3bb..2793420c0 100644 --- a/bin/documentation.py +++ b/bin/documentation.py @@ -47,38 +47,52 @@ def finish(self, index, total, f): lines[0] = first line = " ".join(lines) - line = re.sub(r"\s+", " ", line) - line = re.sub(r"\(\s+", "(", line) - line = re.sub(r"\s+\)", ")", line) - - if index == total - 1 and line[-1] != ".": - line = "{}.".format(line) - - lines = line.split(". ") - lowercase = ["alpha", "or", "where"] - for i, line in enumerate(lines): - if all([not line.startswith(word) for word in lowercase]): - lines[i] = "{}{}".format(line[0].upper(), line[1:]) - line = ". ".join(lines) - - substitutes = { - "Compute": "Computes", - "equal to 1": "equal to one", - } - for key, value in substitutes.items(): - line = re.sub(r"\b{}\b".format(key), value, line) - - chunks = line.split(" ") - lines = [] - count = 0 - while len(chunks) > 0: - current = " ".join(chunks[:count]) - if count == len(chunks) or 4 + len(current) + len(chunks[count]) >= 80: - lines.append(current) - chunks = chunks[count:] - count = 0 - else: - count += 1 + + # Heuristic: We expect that if the text contains an equal sign (`=`) then + # it is not safe to reformat the text. + # + # Holds for: + # * https://github.com/Reference-LAPACK/lapack/blob/master/BLAS/SRC/drotm.f + # * https://github.com/Reference-LAPACK/lapack/blob/master/BLAS/SRC/drotmg.f + # * https://github.com/Reference-LAPACK/lapack/blob/master/BLAS/SRC/dsdot.f + # * https://github.com/Reference-LAPACK/lapack/blob/master/BLAS/SRC/srotm.f + # * https://github.com/Reference-LAPACK/lapack/blob/master/BLAS/SRC/srotmg.f + # + if "=" in line: + pass + else: + line = re.sub(r"\s+", " ", line) + line = re.sub(r"\(\s+", "(", line) + line = re.sub(r"\s+\)", ")", line) + + if index == total - 1 and line[-1] != ".": + line = "{}.".format(line) + + lines = line.split(". ") + lowercase = ["alpha", "or", "where"] + for i, line in enumerate(lines): + if all([not line.startswith(word) for word in lowercase]): + lines[i] = "{}{}".format(line[0].upper(), line[1:]) + line = ". ".join(lines) + + substitutes = { + "Compute": "Computes", + "equal to 1": "equal to one", + } + for key, value in substitutes.items(): + line = re.sub(r"\b{}\b".format(key), value, line) + + chunks = line.split(" ") + lines = [] + count = 0 + while len(chunks) > 0: + current = " ".join(chunks[:count]) + if count == len(chunks) or 4 + len(current) + len(chunks[count]) >= 80: + lines.append(current) + chunks = chunks[count:] + count = 0 + else: + count += 1 self.lines = lines