Fix #231 - switch to pydoctor (#233)

.github/workflows/bump_version.yml

@@ -21,10 +21,11 @@ jobs:
           echo "==== before update ========================="
           cat VERSION
           echo "${{ inputs.version }}" > VERSION
-          sed -i -e "1i <option {{ 'selected' if env['version'] == '${{ inputs.version }}' else '' }} value=\"${{ inputs.version }}\">${{ inputs.version }}</option>" \
-              docs/pdoc_template/version.html.jinja2
+          echo "window._VERSIONS.push('${{ inputs.version }}');" >> docs/template/versions.js
           echo "==== after update ========================="
           cat VERSION
+          echo "==== versions.js ========================="
+          cat docs/template/versions.js
           git add VERSION
       - name: Create Pull Request
         id: cpr

.github/workflows/docs.yml

@@ -28,18 +28,23 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-python@v4
         with:
-          python-version: '3.11'
-      - run: pip install pdoc
+          python-version: '3.10'
+      - run: pip install pydoctor==22.9.1
       - name: build dev build
         if: inputs.version == ''
-        run: pdoc --template-directory ./docs/pdoc_template -o pdocs --footer-text "idnumbers $(cat ./VERSION)+, dev version included" idnumbers
+        run: |
+          pydoctor --make-html --html-output=pydocs/dev --project-name="idnumbers" --project-version=dev --project-url=https://github.com/identique/idnumbers --template-dir=./docs/template idnumbers
+          echo "window._CURRENT_VERSION = 'dev';" > pydocs/dev/current_version.js
       - name: build prod build
         if: inputs.version != ''
-        run: pdoc --template-directory ./docs/pdoc_template -o pdocs --footer-text "idnumbers ${{ inputs.version }}" idnumbers
+        run: |
+          pydoctor --make-html --html-output=pydocs/v${{ inputs.version }} --project-name="idnumbers" --project-version=${{ inputs.version }} --project-url=https://github.com/identique/idnumbers --template-dir=./docs/template idnumbers
+          echo "window._CURRENT_VERSION = '${{ inputs.version }}';" > pydocs/dev/current_version.js
+      - run: cp docs/template/versions.js pydocs/
       - uses: actions/upload-artifact@v3
         with:
           name: apidoc
-          path: pdocs
+          path: pydocs
   deploy:
     needs: build
     runs-on: ubuntu-latest
@@ -50,21 +55,22 @@ jobs:
       - uses: actions/download-artifact@v3
         with:
           name: apidoc
-          path: pdocs
+          path: pydocs
       - run: git config --local user.email "[email protected]"
       - run: git config --local user.name "Microdata Bot"
       - name: deploy dev apidoc
         if: inputs.version == ''
         run: |
-          ls pdocs
-          cp -rf pdocs/* ./docs
+          ls pydocs
+          cp -rf pydocs/* ./docs
           git add ./docs
           git diff-index --quiet HEAD || git commit -m "Update dev doc"
       - name: deploy prod apidoc
         if: inputs.version != ''
         run: |
-          ls pdocs
-          cp -rf pdocs ./docs/v${{ inputs.version }}
+          ls pydocs
+          cp -rf pydocs ./docs/v${{ inputs.version }}
+          cp pydocs/versions.json ./docs/versions.json
           git add ./docs
           git diff-index --quiet HEAD || git commit -m "Add release doc v${{ inputs.version }}"
       - run: git push origin gh-pages

docs/apidoc.md

@@ -1,7 +1,7 @@
 # Generate the API doc for this project
 
 We survey the doc gen tools at the [issue #80](https://github.com/Identique/idnumbers/issues/80). In the end, we
-would like to use the simplest tool, [pdoc](https://pdoc.dev/). It generates the api docs based on
+would like to use the simplest tool, [pydoctor](https://pydoctor.readthedocs.io/en/latest/index.html). It generates the api docs based on
 [docstring](https://peps.python.org/pep-0257/).
 
 We could run the following script to install:
@@ -10,12 +10,12 @@ We could run the following script to install:
 python -m virtualenv doc_env
 doc_env/bin/activate
 
-pip install pdoc
+pip install pydoctor
 ```
 
 And run it:
 ```shell
-pdoc -o pdocs --footer-text "idnumbers $(cat ./VERSION)+, dev version included" idnumbers !idnumbers.nationalid.test_*
+pydoctor --make-html --html-output=docs/$(cat ./VERSION) --project-name="idnumbers" --project-version=$(cat ./VERSION) --project-url=https://github.com/identique/idnumbers --template-dir=./docs/template idnumbers
 ```
 
-It outputs the API docs to a folder named `pdocs`. Have fun with it!
+It outputs the API docs to a folder named `docs/version`. Have fun with it!

docs/template/header.html

@@ -0,0 +1,50 @@
+<head xmlns:t="http://twistedmatrix.com/ns/twisted.web.template/0.1">
+    <meta name="pydoctor-template-version" content="2" />
+    <script type="text/javascript" src="current_version.js"/>
+    <script type="text/javascript" src="../versions.js"/>
+    <script type="text/javascript">
+        window.addEventListener("load", function init() {
+            // change the container style
+            const container = document.getElementById("search-box-container").parentNode;
+            // version text
+            const textSpan = document.createElement("span");
+            textSpan.textContent = "Versions:";
+            textSpan.style.paddingRight = "12px";
+
+            // use div as a group for version dropdown
+            const div = document.createElement("div");
+            div.style.alignSelf = "center";
+            div.style.paddingLeft = "12px";
+            div.classList.add("input-group");
+            // create the select dropdown
+            const select = document.createElement("select");
+            select.classList.add("form-control");
+            select.araLabel= "version dropdown";
+            select.title = "version dropdown";
+            select.style.display = "inline-block";
+            select.style.width = "90px";
+            select.style.float = "none";
+            // dev is always there
+            const devOption = document.createElement("option");
+            devOption.value = "dev";
+            devOption.textContent = "Dev"
+            devOption.selected = window._CURRENT_VERSION === "dev";
+            select.appendChild(devOption);
+            (window._VERSIONS || []).forEach(function(version) {
+                const verOption = document.createElement("option");
+                verOption.value = version;
+                verOption.textContent = version;
+                verOption.selected = window._CURRENT_VERSION === version;
+                select.appendChild(verOption);
+            });
+            select.addEventListener("change", function handleChange(evt) {
+                const version = evt.target.value;
+                window.location = `../v${version}/`;
+            });
+            // put all of them
+            div.appendChild(textSpan);
+            div.appendChild(select);
+            container.insertBefore(div, document.getElementById("search-box-container"));
+        });
+    </script>
+</head>

docs/template/versions.js

@@ -0,0 +1,10 @@
+window._VERSIONS = [];
+window._VERSIONS.push('1.0.0');
+window._VERSIONS.push('1.1.0');
+window._VERSIONS.push('1.2.0');
+window._VERSIONS.push('1.3.0');
+window._VERSIONS.push('1.4.0');
+window._VERSIONS.push('1.5.0');
+window._VERSIONS.push('1.6.0');
+window._VERSIONS.push('1.7.0');
+window._VERSIONS.push('1.8.0');

idnumbers/nationalid/util.py

@@ -83,10 +83,10 @@ def weighted_modulus_digit(numbers: List[int], weights: Optional[List[int]], div
     It metrix-multiples numbers and weights and calculate the modulus by the divider.
     :param numbers: the numbers list.
     :param weights: the weights list which will used in matrix multiplications. If weights is none, we use the
-                    [1] * len(numbers) as the weights.
+    [1] * len(numbers) as the weights.
     :param divider: the divider used for calculating modulus.
-    :param modulus_only: If True, it returns the modulus calculated by divider,
-                         otherwise it returns divider - modulus. The default is False.
+    :param modulus_only: If True, it returns the modulus calculated by divider, otherwise it returns divider - modulus.
+    The default is False.
     :return: the value
     """
     if weights is None: