Feature/markdown conversion (#503)

* feat: markdown conversion

logo and badges

* feat: markdown conversion

fix logo path

* feat: markdown

table changes

* feat: markdown

table alignment

* feat: markdown

check toc

* feat: markdown

toc additions

* feat: markdown

quickstart section

* feat: dependabot

more details section in quick start

* feat: dependabot

correct bold

* feat: markdown

client side config, pip

* feat: markdown

typo in title

* feat: markdown

typo in configuring pip

* feat: markdown

apache like authentication section
an initial cut to view the markdown
in github

* feat: markdown

typo in markdown link

* feat: markdown

remove trailing colon

* feat: markdown

typo in shell markdown

* feat: markdown

standardize on 4 space indent in shell code block

* feat: markdown

complete markdown for section up to alternate installation methods

* feat: markdown

add more of the contents to test with

* feat: markdown

contents

* feat: markdown

contents

* feat: markdown

contents

* feat: markdown
dquote>
dquote> recipes

* feat: markdown
dquote>
dquote> recipes

* feat: markdown
dquote>
dquote> up to licensing

* feat: markdown
dquote>
dquote> contents

* Update README.md

Missing exclamation mark

* Update README.md

missing link

* Update README.md

remove duplicated text

* Update README.md

bold differences it Table of contents

* Update README.md

additional bold changes in table of contents

* Update README.md

broken link

* Update README.md

typo in link fix

* Update README.md

change code block to text as shell highlighting was showing some items in red

* Update README.md

code block shell to text

* Update README.md

correct pypi-server update section

* feat: markdown
dquote>
dquote> link back to TOC title

* Update README.md

change link to TOC title

* Update README.md

link test

* Update README.md

link update

* Update README.md

link update

* Update README.md

link update

* feat: markdown

links

* Update README.md

change the level of indent for uploading packages remotely

* Update README.md

add link to python-pam

* feat: markdown

apache link to TOC not working.

* Update README.md

grammar

* Update README.md

typo bold

* feat: markdown

undo bolded text in TOC and titles as linking does
not work

* feat: markdown

remove bold from TOC

* feat: feature

more link issues

* feat: markdown

fixing broken links

* feat: markdown

change text slightly as markdown only links to plain text

* feat: markdown

typo

* feat: markdown

more link typos

* Update README.md

typo in link

* Update README.md

link will not work with braces in the titles

* feat: markdown

run mdformat and apply changes, :) lint!

* feat:  markdown

- check via mdformat
- remove old check script
- update test-requirements.txt

* feat: markdown

correct the errors in the mdformat run command

* feat: markdown

for testing remove all the actual jobs

* feat: markdown

re-run mdformat

* feat: markdown

put the jobs back in after testing the mdformat
cmd for passing and failing via workflow dispatch

* feat: markdown

remove references to README.md

* feat: markdown

change action to workflow dispatch for testing

* feat: markdown

- update docker igore
- alter unit test to look for version number after md changes

* feat: markdown

black linting

* feat: markdown

update comments

* feat: markdown

update bumpver to look at md rather than rst file

* feat: markdown

replace workflow dispatch with pull request
to get ready for the final PR

* feat: markdown-delete-original

delete the original rst file

* feat: markdown-delete-original

change ci to workflow dispatch for testing

* feat: markdown-delete-original

revert workflow dispatch

* feat: markdown-badge-links

set the links back to the original
URLs.

* feat: markdown-badge-links

fix brackets

* feat: markdown

update the version and date

* feat: markdown conversion

markdown changes to conform to mdformat tooling.

.dockerignore

@@ -4,6 +4,6 @@
 !docker/docker-requirements.txt
 !docker/gunicorn.conf.py
 !docker/entrypoint.sh
-!README.rst
+!README.md
 !setup.cfg
 !setup.py

.github/workflows/ci.yml

@@ -59,7 +59,7 @@ jobs:
       - name: Check formatting
         run: black --diff --check .
       - name: Validate README
-        run: ./bin/check_readme.sh
+        run: mdformat --check README.md
 
   # Full-flow docker tests, again not python version dependent
   # We _could_ test this on MacOS, but it takes forever to get docker

.github/workflows/rc.yml

@@ -7,7 +7,7 @@ name: release_candidate
 # - [x] update CHANGES.rst
 # - [x] create changes commit
 # - [x] push to GH
-# - [ ] update README.rst
+# - [ ] update README.md
 # - [ ] create readme commit
 # - [ ] push to GH
 # - [ ] open a PR to `master`

Dockerfile

@@ -51,7 +51,7 @@ RUN apk add --no-cache --virtual .build-deps \
 COPY pypiserver pypiserver
 COPY setup.cfg .
 COPY setup.py .
-COPY README.rst .
+COPY README.md .
 RUN python -m pip install --no-warn-script-location --prefix=/install .
 
 FROM base

bin/README.rst

@@ -14,7 +14,7 @@ Files:
 
 Release check-list:
 ===================
-1. Update ``/CHANGES.rst`` (+ Title + Date) & ``/README.rst`` (Date,
+1. Update ``/CHANGES.rst`` (+ Title + Date) & ``/README.md`` (Date,
    not version).
 
 2. Push to GitHub to run all TCs once more.

bin/bumpver.py

@@ -49,7 +49,7 @@ VFILE = osp.join(my_dir, "..", "pypiserver", "__init__.py")
 VFILE_regex_v = re.compile(r'version *= *__version__ *= *"([^"]+)"')
 VFILE_regex_d = re.compile(r'__updated__ *= *"([^"]+)"')
 
-RFILE = osp.join(my_dir, "..", "README.rst")
+RFILE = osp.join(my_dir, "..", "README.md")
 
 PYTEST_ARGS = [osp.join("tests", "test_docs.py")]
 

bin/check_readme.sh

@@ -1,37 +0,0 @@
-#!/bin/bash
-#-*- coding: utf-8 -*-
-#
-## Checks that README has no RsT-syntactic errors.
-# Since it is used by `setup.py`'s `description` if it has any errors,
-# PyPi would fail parsing them, ending up with an ugly landing page,
-# when uploaded.
-
->&2 echo "+++ Checking README for PyPy...."
-set +x ## Enable for debug
-
-my_dir=`dirname "$0"`
-cd $my_dir/..
-
-py=""
-rst="rst2html"
-if [ ! -x "`which $rst 2>/dev/null`" ]; then
-    ## In WinPython, only a python-script exist in PATH,
-    #   so execute it with python-interpreter.
-    #
-    exe="`which rst2html.py 2> /dev/null`"
-    if [ $? -eq 0 ]; then
-        py=python
-        rst="$exe"
-    else
-        echo -e "Cannot find 'rst2html'! \n Sphinx installed? `pip show sphinx`" &&
-        exit 1
-    fi
-
-    if [ -x "`which cygpath`" ]; then
-        rst="`cygpath -w $rst`"
-    fi
-fi
-
-export PYTHONPATH='$my_dir/..'
-#python setup.py --long-description > t.rst ## Uncomment to inspect it.
-python setup.py --long-description | $py "$rst"  --halt=warning > /dev/null && echo OK

docs/README.md

@@ -8,7 +8,7 @@ Welcome to the documentation section of `pypiserver`.
 ## More information
 
 If something is missing in the documentation here, maybe it is covered in
-[`README.rst`](../README.rst).
+[README.md](../README.md).
 
 ## Documentation setup
 

requirements/test-requirements.txt

@@ -9,3 +9,6 @@ tox
 twine
 webtest
 wheel>=0.25.0
+mdformat-gfm
+mdformat-frontmatter
+mdformat-footnote

setup.py

@@ -40,7 +40,7 @@ def get_version():
 setup(
     name="pypiserver",
     description="A minimal PyPI server for use with pip/easy_install.",
-    long_description=read_file("README.rst"),
+    long_description=read_file("README.md"),
     version=get_version(),
     packages=["pypiserver"],
     package_data={"pypiserver": ["welcome.html"]},

tests/test_docs.py

@@ -8,10 +8,12 @@ from pypiserver import version as my_ver
 
 @pytest.fixture()
 def readme():
-    return Path(__file__).parents[1].joinpath("README.rst").read_text()
+    return Path(__file__).parents[1].joinpath("README.md").read_text()
 
 
 def test_READMEversion(readme):
-    m = re.compile(r"^\s*:Version:\s*(.+)\s*$", re.MULTILINE).search(readme)
+    m = re.compile(
+        r"^\|\s*Version\s*\|\s*(\d+\.\d+\.\d+)\s*\|$", re.MULTILINE
+    ).search(readme)
     assert m, "Could not find version on README!"
     assert m.group(1) == my_ver, f"Updated version({m.group(1)}) on README!"