Issue 30. update RTD for pypi (#31)

* Issue 30. update RTD for pypi * Issue 30. update RTD for pypi * Issue 30, update RTD * Issue 30, update RTD * Issue 30, update RTD * Issue 30, update RTD * Issue 30, update RTD * Issue 30. update RTD for pypi * Issue 30. Update RTD for pypi. Update sphix requirements.txt for RTD * Issue 30. Update RTD for pypi. Update sphix requirements.txt for RTD * Issue 30. Update RTD for pypi. Update sphix requirements.txt for RTD * Issue 30. Update RTD for pypi. See Issue 32 for Sphinx requirement.txt Python 3.7 Pandas build problem
UAL-RE · Jul 7, 2022 · 84866f0 · 84866f0
1 parent 9b098cd
commit 84866f0
Show file tree

Hide file tree

Showing 2 changed files with 53 additions and 1 deletion.
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -3,4 +3,5 @@ sphinx-rtd-theme==0.5.1
 sphinx-autodoc-typehints==1.11.1
 
 # for logger module
-pandas==1.4.3
+pandas==1.2.3
+
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -14,3 +14,54 @@ From :repo:`source <>`:
 
    (venv) $ git clone git@github.com:UAL-RE/redata-commons.git
    (venv) $ python setup.py install
+
+Check packages installed
+
+::
+
+   (venv) $ pip freeze
+
+Note:  
+This beautiful table for Conda vs. pip https://docs.conda.io/projects/conda/en/latest/commands.html#conda-vs-pip-vs-virtualenv-commands
+
+
+Updating ``redata-commons`` 
+---------------------------
+
+``redata-commons`` has a typical Python repository structrure. A good reading can be found on The Hitchhiker's Guide to Python: Best Practices for Development 
+at https://docs.python-guide.org/writing/structure/
+
+There are a few files to updated for a new version: 
+ 1. ``requirements.txt`` : redata-common required dependencies
+ 2. ``setup.py`` :  Package and distribution management 
+ 3. ``CHANGELOG.md``: 
+ 4. ``README.md`` : README file. 
+ 5. ``/docs/requirements.text``: Sphinx required dependencies. It may need to be updated.
+ 6. ``/docs/source/conf.py``: Configuration file for Sphinx RTD
+ 7. ``/docs/source/*.rst`` : RTD source files. These might need to be updated
+ 8. ``.github/workflows/pypi-publish.yml``: workflow publishing to pypi.org
+
+Building and Publishing ``redata-commons`` in pypi.org 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Directories ``build/``,  ``dist/``, the egg file ``redata.egg-info`` and so on (see .gitignore) are generated when running on building the package. Use the following first command 
+to see the available parameters. The 2nd command is to build the package.
+
+:: 
+
+    (venv) $ python setup.py --help-commands
+    (venv) $ python setup.py sdist bdist_wheel
+
+
+After creating a pull request, workflow actions will be run/compile/test to check the updated code. One of the workflows automatically publish ``redata-commons`` in pypi.org, using its workflows at ``.github/workflows/pypi-publish.yml``. 
+
+Best Practices for using a Python ``requirements.txt`` 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following are best practices:  
+ 1. Use ``pip freeze`` to generate a list of Python modules and packages installed in the virtual env.
+ 2. ONLY list the modules and packages needed. Do NOT include unneccssary packages, as this makes upgrade extra efforts. It is also a waste of resources.
+ 3. Keep requirements.txt file up to date and accurate. This ensure the project always use the latest version of of the Python modules and packages.
+
+
+