Repository: pyjanitor-devs/pyjanitor

Issue:
[DOC] Missing Pyjanitor description on PyPi
# Brief Description of Fix

Since `pyjanitor` release `0.22.0`, there has not been a ["Project description" for the package on PyPi](https://pypi.org/project/pyjanitor/0.22.0/#description).

During the release of of `0.24.0`, @samukweku and I got an error during the release process due to:

```
Checking dist/pyjanitor-0.24.0-py3-none-any.whl: FAILED
ERROR    `long_description` has syntax errors in markup and would not be        
         rendered on PyPI.                                                      
         No content rendered from RST source.     
```
Our guess is that we had switched the README from RST to MD some time ago, causing the `long_description` to quietly fail, and now the `gh-action-pypi-publish` GitHub action would no longer accept the bad `long_description`.

We updated the `long_description_content_type` in `setup.py` to markdown  in #1197  and the package was successfully published to PyPi, but there is still no Project description. So there must still be something that is not being generated correctly.

We need to verify that `long_description` is properly being generated. We should test with local tools *and* https://test.pypi.org/ to verify that this is fixed.


Discussion:
It's due to this logic in `setup.py`

```python
    # Find pypi-doc comments in README
    indices = [m.start() for m in re.finditer(".. pypi-doc", readme)]
    if len(indices) % 2 != 0:
        raise Exception("Odd number of `.. pypi-doc` comments in README")

    # Loop through pairs of comments and save text between pairs
    long_description = ""
    for i in range(0, len(indices), 2):
        start_index = indices[i] + 11
        end_index = indices[i + 1]
        long_description += readme[start_index:end_index]
    return long_description
```

introduced in [this commit](https://github.com/pyjanitor-devs/pyjanitor/commit/c94ebe4bbf5b1fed2a4c4bb79e76e93aaab8930b) originally.

No more `.. pypi-doc` markers exist, so `long_description == ""` the empty string.

---

For the fix, we can naively apply something similar to the original implemention in the form of html comment markup, maybe.  `<!-- pypi-doc -->` like so.

To verify: Run `twine check` to make sure the warning is gone.

Resolving patch:
diff --git a/setup.py b/setup.py
--- a/setup.py
+++ b/setup.py
@@ -68,7 +68,7 @@ def read_requirements(*parts):
 
 # add 'all' key to EXTRA_REQUIRES
 all_requires = []
-for k, v in EXTRA_REQUIRES.items():
+for _, v in EXTRA_REQUIRES.items():
     all_requires.extend(v)
 EXTRA_REQUIRES["all"] = set(all_requires)
 
@@ -83,11 +83,11 @@ def generate_long_description() -> str:
     """
     Extra chunks from README for PyPI description.
 
-    Target chunks must be contained within `.. pypi-doc` pair comments,
+    Target chunks must be contained within `<!-- pypi-doc -->` pair comments,
     so there must be an even number of comments in README.
 
     :returns: Extracted description from README.
-    :raises Exception: if odd number of `.. pypi-doc` comments
+    :raises Exception: If odd number of `<!-- pypi-doc -->` comments
         in README.
     """
     # Read the contents of README file
@@ -96,14 +96,15 @@ def generate_long_description() -> str:
         readme = f.read()
 
     # Find pypi-doc comments in README
-    indices = [m.start() for m in re.finditer(".. pypi-doc", readme)]
+    boundary = r"<!-- pypi-doc -->"
+    indices = [m.start() for m in re.finditer(boundary, readme)]
     if len(indices) % 2 != 0:
-        raise Exception("Odd number of `.. pypi-doc` comments in README")
+        raise Exception(f"Odd number of `{boundary}` comments in README")
 
     # Loop through pairs of comments and save text between pairs
     long_description = ""
     for i in range(0, len(indices), 2):
-        start_index = indices[i] + 11
+        start_index = indices[i] + len(boundary)
         end_index = indices[i + 1]
         long_description += readme[start_index:end_index]
     return long_description


Test patch: