2017-09-07

.gitignore

@@ -1,6 +1,8 @@
 # User Settings
-elementary_math.egg-info
-start-a-project/elementary_math-project
+elementary_math_venv/
+elementary_math.egg-info/
+elementary_math-*/
+start-a-project/*-project/
 *index.rst
 
 # Byte-compiled / optimized / DLL files

Makefile

@@ -64,37 +64,47 @@ USE_PYENV="Y"
 BUCKET_NAME="www.wbh-doc.com"
 
 #--- Derive Other Variable ---
-ifeq ($(USE_PYENV), "Y")
-    BIN_ACTIVATE="${HOME}/.pyenv/versions/${PY_VERSION}/envs/${VENV_NAME}/bin/activate"
-    BIN_PYTHON="${HOME}/.pyenv/versions/${PY_VERSION}/envs/${VENV_NAME}/bin/python"
-    BIN_PIP="${HOME}/.pyenv/versions/${PY_VERSION}/envs/${VENV_NAME}/bin/pip"
-    BIN_PYTEST="${HOME}/.pyenv/versions/${PY_VERSION}/envs/${VENV_NAME}/bin/pytest"
-    BIN_SPHINX_START="${HOME}/.pyenv/versions/${PY_VERSION}/envs/${VENV_NAME}/bin/sphinx-quickstart"
-    BIN_TWINE="${HOME}/.pyenv/versions/${PY_VERSION}/envs/${VENV_NAME}/bin/twine"
+# Windows
+ifeq (${OS}, Windows_NT)
+    DETECTED_OS := Windows
+    USE_PYENV="N"
 
-    VENV_DIR_REAL="${HOME}/.pyenv/versions/${PY_VERSION}/envs/${VENV_NAME}"
-    VENV_DIR_LINK="${HOME}/.pyenv/versions/${VENV_NAME}"
+    BIN_DIR="./${VENV_NAME}/Scripts"
+    VENV_DIR_REAL="./${VENV_NAME}"
+    SITE_PACKAGES="./${VENV_NAME}/Lib/site-packages"
 
-    SITE_PACKAGES="${HOME}/.pyenv/versions/${PY_VERSION}/envs/${VENV_NAME}/lib/python${PY_VER_MAJOR}.${PY_VER_MINOR}/site-packages"
+    GLOBAL_PYTHON="/c/Python${PY_VER_MAJOR}${PY_VER_MINOR}/python.exe"
+    OPEN_COMMAND="start"
+# MacOS or Linux
 else
-    BIN_ACTIVATE="./${VENV_NAME}/bin/activate"
-    BIN_PYTHON="./${VENV_NAME}/bin/python"
-    BIN_PIP="./${VENV_NAME}/bin/pip"
-    BIN_PYTEST="./${VENV_NAME}/bin/pytest"
-    BIN_SPHINX_START="./${VENV_NAME}/bin/sphinx-quickstart"
-    BIN_TWINE="./${VENV_NAME}/bin/twine"
 
+ifeq ($(USE_PYENV), "Y")
+    BIN_DIR="${HOME}/.pyenv/versions/${PY_VERSION}/envs/${VENV_NAME}/bin"
+    VENV_DIR_REAL="${HOME}/.pyenv/versions/${PY_VERSION}/envs/${VENV_NAME}"
+    VENV_DIR_LINK="${HOME}/.pyenv/versions/${VENV_NAME}"
+    SITE_PACKAGES="${VENV_DIR_REAL}/lib/python${PY_VER_MAJOR}.${PY_VER_MINOR}/site-packages"
+else
+    BIN_DIR="./${VENV_NAME}/bin"
     VENV_DIR_REAL="./${VENV_NAME}"
     VENV_DIR_LINK="./${VENV_NAME}"
+    SITE_PACKAGES="${VENV_DIR_REAL}/lib/python${PY_VER_MAJOR}.${PY_VER_MINOR}/site-packages"
+endif
 
-    SITE_PACKAGES="${HOME}/.pyenv/versions/${PY_VERSION}/envs/${VENV_NAME}/lib/python${PY_VER_MAJOR}.${PY_VER_MINOR}/site-packages"
+    GLOBAL_PYTHON="python${PY_VER_MAJOR}.${PY_VER_MINOR}"
+    OPEN_COMMAND="open"
 endif
 
+BIN_ACTIVATE="${BIN_DIR}/activate"
+BIN_PYTHON="${BIN_DIR}/python"
+BIN_PIP="${BIN_DIR}/pip"
+BIN_PYTEST="${BIN_DIR}/pytest"
+BIN_SPHINX_START="${BIN_DIR}/sphinx-quickstart"
+BIN_TWINE="${BIN_DIR}/twine"
+
 S3_PREFIX="s3://${BUCKET_NAME}/${PACKAGE_NAME}"
 DOC_URL="http://${BUCKET_NAME}.s3.amazonaws.com/${PACKAGE_NAME}/index.html"
 
 PY_VERSION="${PY_VER_MAJOR}.${PY_VER_MINOR}.${PY_VER_PATCH}"
-GLOBAL_PYTHON="python${PY_VER_MAJOR}.${PY_VER_MINOR}"
 
 
 .PHONY: help
@@ -150,6 +160,7 @@ ifeq (${USE_PYENV}, "Y")
 
 	-pyenv virtualenv ${VENV_NAME}
 else
+	echo
 	virtualenv -p ${GLOBAL_PYTHON} ${VENV_NAME}
 endif
 
@@ -243,7 +254,7 @@ clean_doc: ## Clean Existing Documents
 
 .PHONY: view_doc
 view_doc: ## Open Documents
-	open ./docs/build/html/index.html
+	${OPEN_COMMAND} ./docs/build/html/index.html
 
 
 .PHONY: reformat
@@ -258,4 +269,4 @@ publish: ## Publish This Library to PyPI
 	${BIN_PIP} install 'twine>=1.5.0'
 	${BIN_PYTHON} setup.py sdist bdist_wheel
 	${BIN_TWINE} upload dist/*
-	-rm -rf build dist .egg ${PACKAGE_NAME}.egg-info
+	-rm -rf build dist .egg ${PACKAGE_NAME}.egg-info

README.rst

@@ -16,6 +16,8 @@
 .. image:: https://img.shields.io/badge/Star_Me_on_GitHub!--None.svg?style=social
     :target: https://github.com/MacHu-GWU/elementary_math-project
 
+.. contents::
+
 
 Welcome to ``elementary_math`` Documentation
 ============================================
@@ -29,7 +31,7 @@ Welcome to ``elementary_math`` Documentation
 - code coverage test with coverall
 - multi python version test with tox
 - integration with https://travis-ci.org/
-- integration with https://coveralls.io/
+- integration with https://codecov.io/
 - auto deploy to `AWS S3 <http://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html>`_
 - publish to `PyPI <https://pypi.python.org/pypi/your-package-name>`_
 
@@ -47,16 +49,71 @@ Quick Links
 Usage
 -----
 1. Clone the repo.
-2. Navigate to ``elementary_math-project/start-a-project``, edit ``init_project.py`` and runt.
+2. Navigate to ``elementary_math-project/start-a-project``, edit ``init_project.py`` and run it.
 3. A ``<repo-name>`` directory will be created, you can use this as your github repo directory.
+4. Take a look at ``Makefile``, all magic happens here!
+
+
+AWS Command Line (Optional)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Use `AWS S3 <http://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html>`_ to host your doc site is a good idea!
+
+We need `awscli <https://aws.amazon.com/cli/>`_ to automate the deployment.
+
+1. Install `awscli <https://aws.amazon.com/cli/>`_, just ``pip install awscli``.
+2. `Configure your API token <http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html>`_, just ``aws configure`` and follow the instruction.
+
+
+Config PyPI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you want to publish your package to `PyPI <https://pypi.python.org/pypi>`_ or `new PyPI <https://pypi.org/>`_, you need a pypi account and `Configure your credential <https://docs.python.org/2/distutils/packageindex.html#pypirc>`_.
+
+1. Create a ``${HOME}/.pypirc`` file.
+2. put these contents::
+
+    [distutils]
+    index-servers =
+        pypi
+
+    [pypi]
+    username:<username>
+    password:<password>
 
-**For MacOS**:
 
+For Windows
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Because Windows doesn't have ``shell script`` and ``make`` command, so we have to install some third-party software to make it works.
+
+**Install Git Bash as shell emulator**
+
+1. `Download and install git <https://git-scm.com/downloads>`_.
+2. Now you can use ``C:\Program Files\Git\git-bash.exe`` like the terminal in MacOS/Linux.
+
+**Install MinGW**
+
+1. `Download and install <http://www.mingw.org/>`_, use the installer to install ``MinGW Base``.
+2. Find ``C:\MinGW\bin\mingw32-make.exe``, copy and paste and rename as ``C:\MinGW\bin\make.exe``.
+3. Add ``C:\MinGW\bin`` to $PATH (environment variable).
+
+Now you can use ``make <target>`` in ``git-bash.exe`` now.
+
+
+For MacOS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 You have to make sure:
 
 - `HomeBrew <https://brew.sh/>`_ is installed.
 
-take a look at ``Makefile``, all magic happens here!
+There's two way of using virtualenv in MacOS:
+
+1. Use generic `virtualenv <https://virtualenv.pypa.io/en/stable/>`_.
+2. Use `pyenv <https://github.com/pyenv/pyenv>`_ + `pyenv-virtualenv <https://github.com/pyenv/pyenv-virtualenv>`_.
+
+I prefer ``pyenv`` + ``pyenv-virtualenv``, because it allows you:
+
+1. use tox to test against multiple python version locally before using cloud CI (continues integration).
+2. will not mess up your global python environment.
+3. the ``Makefile`` will do the ``pyenv`` + ``pyenv-virtualenv`` setup for you, just make sure that you have  `HomeBrew <https://brew.sh/>`_ installed.
 
 
 .. _install:

elementary_math/__init__.py

@@ -5,7 +5,7 @@
 Elementary Math Library. (For demonstration purpose only)
 """
 
-__version__ = "0.0.7"
+__version__ = "0.0.8"
 __short_description__ = "Elementary Mathematics."
 __license__ = "MIT"
 __author__ = "Sanhe Hu"

start-a-project/template/.gitignore

@@ -1,5 +1,7 @@
 # User Settings
-{{ package_name }}.egg-info
+{{ package_name }}_venv/
+{{ package_name }}.egg-info/
+{{ package_name }}-*/
 index.rst
 
 # Byte-compiled / optimized / DLL files

start-a-project/template/Makefile

@@ -64,37 +64,47 @@ USE_PYENV="Y"
 BUCKET_NAME="www.wbh-doc.com"
 
 #--- Derive Other Variable ---
-ifeq ($(USE_PYENV), "Y")
-    BIN_ACTIVATE="${HOME}/.pyenv/versions/${PY_VERSION}/envs/${VENV_NAME}/bin/activate"
-    BIN_PYTHON="${HOME}/.pyenv/versions/${PY_VERSION}/envs/${VENV_NAME}/bin/python"
-    BIN_PIP="${HOME}/.pyenv/versions/${PY_VERSION}/envs/${VENV_NAME}/bin/pip"
-    BIN_PYTEST="${HOME}/.pyenv/versions/${PY_VERSION}/envs/${VENV_NAME}/bin/pytest"
-    BIN_SPHINX_START="${HOME}/.pyenv/versions/${PY_VERSION}/envs/${VENV_NAME}/bin/sphinx-quickstart"
-    BIN_TWINE="${HOME}/.pyenv/versions/${PY_VERSION}/envs/${VENV_NAME}/bin/twine"
+# Windows
+ifeq (${OS}, Windows_NT)
+    DETECTED_OS := Windows
+    USE_PYENV="N"
 
-    VENV_DIR_REAL="${HOME}/.pyenv/versions/${PY_VERSION}/envs/${VENV_NAME}"
-    VENV_DIR_LINK="${HOME}/.pyenv/versions/${VENV_NAME}"
+    BIN_DIR="./${VENV_NAME}/Scripts"
+    VENV_DIR_REAL="./${VENV_NAME}"
+    SITE_PACKAGES="./${VENV_NAME}/Lib/site-packages"
 
-    SITE_PACKAGES="${HOME}/.pyenv/versions/${PY_VERSION}/envs/${VENV_NAME}/lib/python${PY_VER_MAJOR}.${PY_VER_MINOR}/site-packages"
+    GLOBAL_PYTHON="/c/Python${PY_VER_MAJOR}${PY_VER_MINOR}/python.exe"
+    OPEN_COMMAND="start"
+# MacOS or Linux
 else
-    BIN_ACTIVATE="./${VENV_NAME}/bin/activate"
-    BIN_PYTHON="./${VENV_NAME}/bin/python"
-    BIN_PIP="./${VENV_NAME}/bin/pip"
-    BIN_PYTEST="./${VENV_NAME}/bin/pytest"
-    BIN_SPHINX_START="./${VENV_NAME}/bin/sphinx-quickstart"
-    BIN_TWINE="./${VENV_NAME}/bin/twine"
 
+ifeq ($(USE_PYENV), "Y")
+    BIN_DIR="${HOME}/.pyenv/versions/${PY_VERSION}/envs/${VENV_NAME}/bin"
+    VENV_DIR_REAL="${HOME}/.pyenv/versions/${PY_VERSION}/envs/${VENV_NAME}"
+    VENV_DIR_LINK="${HOME}/.pyenv/versions/${VENV_NAME}"
+    SITE_PACKAGES="${VENV_DIR_REAL}/lib/python${PY_VER_MAJOR}.${PY_VER_MINOR}/site-packages"
+else
+    BIN_DIR="./${VENV_NAME}/bin"
     VENV_DIR_REAL="./${VENV_NAME}"
     VENV_DIR_LINK="./${VENV_NAME}"
+    SITE_PACKAGES="${VENV_DIR_REAL}/lib/python${PY_VER_MAJOR}.${PY_VER_MINOR}/site-packages"
+endif
 
-    SITE_PACKAGES="${HOME}/.pyenv/versions/${PY_VERSION}/envs/${VENV_NAME}/lib/python${PY_VER_MAJOR}.${PY_VER_MINOR}/site-packages"
+    GLOBAL_PYTHON="python${PY_VER_MAJOR}.${PY_VER_MINOR}"
+    OPEN_COMMAND="open"
 endif
 
+BIN_ACTIVATE="${BIN_DIR}/activate"
+BIN_PYTHON="${BIN_DIR}/python"
+BIN_PIP="${BIN_DIR}/pip"
+BIN_PYTEST="${BIN_DIR}/pytest"
+BIN_SPHINX_START="${BIN_DIR}/sphinx-quickstart"
+BIN_TWINE="${BIN_DIR}/twine"
+
 S3_PREFIX="s3://${BUCKET_NAME}/${PACKAGE_NAME}"
 DOC_URL="http://${BUCKET_NAME}.s3.amazonaws.com/${PACKAGE_NAME}/index.html"
 
 PY_VERSION="${PY_VER_MAJOR}.${PY_VER_MINOR}.${PY_VER_PATCH}"
-GLOBAL_PYTHON="python${PY_VER_MAJOR}.${PY_VER_MINOR}"
 
 
 .PHONY: help
@@ -150,6 +160,7 @@ ifeq (${USE_PYENV}, "Y")
 
 	-pyenv virtualenv ${VENV_NAME}
 else
+	echo
 	virtualenv -p ${GLOBAL_PYTHON} ${VENV_NAME}
 endif
 
@@ -243,7 +254,7 @@ clean_doc: ## Clean Existing Documents
 
 .PHONY: view_doc
 view_doc: ## Open Documents
-	open ./docs/build/html/index.html
+	${OPEN_COMMAND} ./docs/build/html/index.html
 
 
 .PHONY: reformat