build: Use poetry for building, update docs and Makefiles (#270)

See also: vcs-python/vcspull#303

Author: tony

.github/workflows/libvcs-ci.yml renamed to .github/workflows/tests.yml

@@ -1,4 +1,4 @@
-name: libvcs CI
+name: tests
 
 on: [push]
 
@@ -61,7 +61,7 @@ jobs:
       run: poetry run python -m pip install pip -U
 
     - name: Install dependencies
-      run: poetry install -E "docs test coverage lint format deploy"
+      run: poetry install -E "docs test coverage lint format"
 
     - name: Lint with flake8
       run: poetry run flake8

.gitignore

@@ -80,9 +80,3 @@ pip-wheel-metadata/
 
 # Used by publish-docs.yml CI
 .updated_files
-
-# mkdocs
-site/
-
-# vim
-.vim/

CHANGES

@@ -8,7 +8,7 @@ Generally speaking, refactor / magic is in the process of being stripped
 out in the next few releases. The API is subject to change significantly
 in pre-1.0 builds.
 
-- [refactor] [#267](https://github.com/vcs-python/libvcs/pull/267) overhaul docs
+- [refactor] [#267] overhaul docs
 
   - Move sphinx api format to Numpy-style
 
@@ -18,13 +18,20 @@ in pre-1.0 builds.
 
   - Move from RTD to GitHub Action, full support of poetry extras packages, deploys straight to
     S3 and CloudFront
+- [#270] Build and publish packages via poetry
+- [#270] Overhaul development docs
+
+[#270]: https://github.com/vcs-python/libvcs/pull/270
+[#267]: https://github.com/vcs-python/libvcs/pull/267
 
 ## libvcs 0.4.4 (2020-08-05)
 
-- `268` `libvcs.base.BaseRepo`:
+- [#268] `libvcs.base.BaseRepo`:
     - no longer sets `**kwargs` to dictionary on the object
     - remove `__slot__` and rename `name` attribute to `repo_name`
 
+[#268]: https://github.com/vcs-python/libvcs/pull/268
+
 ## libvcs 0.4.3 (2020-08-01)
 
 - \[bug\] `libvcs.git.extract_status()` Fix issue capturing branch
@@ -112,12 +119,14 @@ avoid implicit behavior.
 ## libvcs 0.3.1 (2020-07-25)
 
 - Fix issue with subprocess.Popen loud warning on Python 3.8
-- `296` - Move from Pipfile to poetry
+- [#296] - Move from Pipfile to poetry
 - Sort imports
 - Add isort package, isort configuration in setup.cfg, and
     `make isort` task to Makefile.
 - Add `project_urls` to setup.py
 
+[#296] https://github.com/vcs-python/libvcs/pull/296
+
 ## libvcs 0.3.0 (2018-03-12)
 
 - Move vcspull to the vcs-python organization
@@ -137,8 +146,9 @@ avoid implicit behavior.
 
 ## libvcs 0.2.2 (2016-11-23)
 
-- Fix bug with unused `support` module in vcspull. See
-    [\#43](https://github.com/vcs-python/vcspull/issues/43)
+- Fix bug with unused `support` module in vcspull. See [vcspull#43]
+
+[vcspull#43]: https://github.com/vcs-python/vcspull/pull/43
 
 ## libvcs 0.2.1 (2016-09-13)
 
@@ -150,11 +160,14 @@ avoid implicit behavior.
 
 ## libvcs 0.2.0 (2016-06-24)
 
-- `9` Support for `progress_callback` to use realtime output from
+- [#9] Support for `progress_callback` to use realtime output from
     commands in progress (such as `git fetch`).
-- `9` More tests, internal factoring and documentation, thanks @jcfr
-- `9` Official support for pypy, pypy3
-- `11` : Fix unbound local when updating git repos
+- [#9] More tests, internal factoring and documentation, thanks @jcfr
+- [#9] Official support for pypy, pypy3
+- [#11] : Fix unbound local when updating git repos
+
+[#9]: https://github.com/vcs-python/libvcs/pull/9
+[#11]: https://github.com/vcs-python/libvcs/pull/11
 
 ## libvcs 0.1.7 (2016-06-21)
 

MANIFEST.in

@@ -1,3 +1,2 @@
 include README.md LICENSE CHANGES pyproject.toml .tmuxp.yaml
-include requirements/*.txt
 recursive-include docs *.rst

Makefile

@@ -1,5 +1,6 @@
 PY_FILES= find . -type f -not -path '*/\.*' | grep -i '.*[.]py$$' 2> /dev/null
 DOC_FILES= find . -type f -not -path '*/\.*' | grep -i '.*[.]rst\$\|.*[.]md\$\|.*[.]css\$\|.*[.]py\$\|mkdocs\.yml\|CHANGES\|TODO\|.*conf\.py' 2> /dev/null
+SHELL := /bin/bash
 
 
 entr_warn:
@@ -23,19 +24,19 @@ watch_test:
 	if command -v entr > /dev/null; then ${PY_FILES} | entr -c $(MAKE) test; else $(MAKE) test entr_warn; fi
 
 build_docs:
-	poetry run mkdocs build
+	$(MAKE) -C docs html
 
 watch_docs:
 	if command -v entr > /dev/null; then ${DOC_FILES} | entr -c $(MAKE) build_docs; else $(MAKE) build_docs entr_warn; fi
 
 serve_docs:
-	python -m http.server --directory site
+	$(MAKE) -C docs serve
 
 dev_docs:
 	$(MAKE) -j watch_docs serve_docs
 
 flake8:
-	flake8 libvcs tests
+	poetry run flake8
 
 watch_flake8:
 	if command -v entr > /dev/null; then ${PY_FILES} | entr -c $(MAKE) flake8; else $(MAKE) flake8 entr_warn; fi

README.rst

@@ -2,7 +2,8 @@
 
 |pypi| |docs| |build-status| |coverage| |license|
 
-Install:
+Setup
+-----
 
 .. code-block:: sh
 
@@ -18,6 +19,8 @@ Open up python:
    $ pip install ptpython
    $ ptpython
 
+Usage
+-----
 Create a `Repo`_ object of the project to inspect / checkout / update:
 
 .. code-block:: python
@@ -50,7 +53,6 @@ Get revision:
 
 Donations
 ---------
-
 Your donations fund development of new features, testing and support.
 Your money will go directly to maintenance and development of the project.
 If you are an individual, feel free to give whatever feels right for the
@@ -60,33 +62,17 @@ See donation options at https://www.git-pull.com/support.html.
 
 More information 
 ----------------
-
-==============  ==========================================================
-Python support  Python 2.7, >= 3.4, pypy
-VCS supported   git(1), svn(1), hg(1)
-Source          https://github.com/vcs-python/libvcs
-Docs            https://libvcs.git-pull.com
-Changelog       https://libvcs.git-pull.com/history.html
-API             https://libvcs.git-pull.com/api.html
-Issues          https://github.com/vcs-python/libvcs/issues
-Test Coverage   https://codecov.io/gh/vcs-python/libvcs
-pypi            https://pypi.python.org/pypi/libvcs
-Open Hub        https://www.openhub.net/p/libvcs
-License         `MIT`_.
-git repo        .. code-block:: bash
-
-                    $ git clone https://github.com/vcs-python/libvcs.git
-install dev     .. code-block:: bash
-
-                    $ git clone https://github.com/vcs-python/libvcs.git libvcs
-                    $ cd ./libvcs
-                    $ virtualenv .venv
-                    $ source .venv/bin/activate
-                    $ pip install -e .
-tests           .. code-block:: bash
-
-                    $ py.test
-==============  ==========================================================
+- Python support: Python 2.7, >= 3.4, pypy
+- VCS supported: git(1), svn(1), hg(1)
+- Source: https://github.com/vcs-python/libvcs
+- Docs: https://libvcs.git-pull.com
+- Changelog: https://libvcs.git-pull.com/history.html
+- API: https://libvcs.git-pull.com/api.html
+- Issues: https://github.com/vcs-python/libvcs/issues
+- Test Coverage: https://codecov.io/gh/vcs-python/libvcs
+- pypi: https://pypi.python.org/pypi/libvcs
+- Open Hub: https://www.openhub.net/p/libvcs
+- License: `MIT`_.
 
 .. _MIT: https://opensource.org/licenses/MIT
 .. _Documentation: https://libvcs.git-pull.com/
@@ -99,13 +85,13 @@ tests           .. code-block:: bash
     :alt: Python Package
     :target: http://badge.fury.io/py/libvcs
 
-.. |docs| image:: https://github.com/tony/libvcs/workflows/Publish%20Docs/badge.svg
+.. |docs| image:: https://github.com/vcs-python/libvcs/workflows/Publish%20Docs/badge.svg
    :alt: Docs
    :target: https://github.com/vcs-python/libvcs/actions?query=workflow%3A"Publish+Docs"
 
-.. |build-status| image:: https://github.com/tony/libvcs/workflows/libvcs%20CI/badge.svg
+.. |build-status| image:: https://github.com/vcs-python/libvcs/workflows/tests/badge.svg
    :alt: Build Status
-   :target: https://github.com/vcs-python/libvcs/actions?query=workflow%3A"libvcs+CI"
+   :target: https://github.com/vcs-python/libvcs/actions?query=workflow%3A"tests"
 
 .. |coverage| image:: https://codecov.io/gh/vcs-python/libvcs/branch/master/graph/badge.svg
     :alt: Code Coverage

docs/Makefile

@@ -159,7 +159,7 @@ checkbuild:
 	rm -rf $(BUILDDIR)
 	$(SPHINXBUILD) -n -q ./ $(BUILDDIR)
 
-WATCH_FILES= find .. -type f -not -path '*/\.*' | grep -i '.*[.]rst\$\|.*[.]py\$\|CHANGES\|TODO\|.*conf\.py' 2> /dev/null
+WATCH_FILES= find .. -type f -not -path '*/\.*' | grep -i '.*[.]rst\$\|.*[.].md\|.*[.]py\$\|CHANGES\|TODO\|.*conf\.py' 2> /dev/null
 
 watch:
 	if command -v entr > /dev/null; then ${WATCH_FILES} | entr -c $(MAKE) html; else $(MAKE) html; fi

docs/_static/favicon.ico

@@ -1,9 +1,14 @@
 # -*- coding: utf-8 -*-
+import inspect
 import os
+import sys
+from os.path import dirname, relpath
 
 import alagitpull
 from recommonmark.transform import AutoStructify
 
+import libvcs
+
 # Get the project root dir, which is the parent dir of this
 cwd = os.getcwd()
 project_root = os.path.dirname(cwd)
@@ -128,3 +133,74 @@ def setup(app):
     'py': ('https://docs.python.org/2', None),
     'pip': ('http://pip.readthedocs.io/en/latest/', None),
 }
+
+
+def linkcode_resolve(domain, info):  # NOQA: C901
+    """
+    Determine the URL corresponding to Python object
+
+    Notes
+    -----
+    From https://github.com/numpy/numpy/blob/v1.15.1/doc/source/conf.py, 7c49cfa
+    on Jul 31. License BSD-3. https://github.com/numpy/numpy/blob/v1.15.1/LICENSE.txt
+    """
+    if domain != 'py':
+        return None
+
+    modname = info['module']
+    fullname = info['fullname']
+
+    submod = sys.modules.get(modname)
+    if submod is None:
+        return None
+
+    obj = submod
+    for part in fullname.split('.'):
+        try:
+            obj = getattr(obj, part)
+        except Exception:
+            return None
+
+    # strip decorators, which would resolve to the source of the decorator
+    # possibly an upstream bug in getsourcefile, bpo-1764286
+    try:
+        unwrap = inspect.unwrap
+    except AttributeError:
+        pass
+    else:
+        obj = unwrap(obj)
+
+    try:
+        fn = inspect.getsourcefile(obj)
+    except Exception:
+        fn = None
+    if not fn:
+        return None
+
+    try:
+        source, lineno = inspect.getsourcelines(obj)
+    except Exception:
+        lineno = None
+
+    if lineno:
+        linespec = "#L%d-L%d" % (lineno, lineno + len(source) - 1)
+    else:
+        linespec = ""
+
+    fn = relpath(fn, start=dirname(libvcs.__file__))
+
+    if 'dev' in about['__version__']:
+        return "%s/blob/master/%s/%s%s" % (
+            about['__github__'],
+            about['__package_name__'],
+            fn,
+            linespec,
+        )
+    else:
+        return "%s/blob/v%s/%s/%s%s" % (
+            about['__github__'],
+            about['__version__'],
+            about['__package_name__'],
+            fn,
+            linespec,
+        )