PyDocuShare

This is the git repository of PyDocuShare, python API to interact with DocuShare.

The user documentation is available at https://tmtsoftware.github.io/cont-pydocushare/ .

This README.md is the documentation for developers who extend, fix and/or release PyDocuShare API.

License

PyDocuShare uses pyduktape as the underlying JavaScript interpreter to perform DocuShare challenge-response authentication. Because it is distributed under the terms of GNU General Public License version 2, PyDocuShare is distributed under the same license. See LICENSE for more details.

Editable installation

If you want to test PyDocuShare under development, you may want to have the system recognize docushare module in your local git repository rather than installing them in one of python system paths. To do so, run the command below:

 $ pip install -e .

The command above adds docusahre module in your local git repository to the python system paths. It is called "editable installs". You can undo the command above by running:

 $ pip uninstall pydocushare

Inline Documentation

PyDocuShare uses numpy style to document the module, classes, functions, methods and attributes. Use the same style for consistency.

Documentation

PyDocuShare uses Sphinx to generate the user documentation and API reference. They are published at https://tmtsoftware.github.io/cont-pydocushare/ through GitHug Pages.

The source files of user documentation can be found under docs/. If you want to generate the user documentation and API reference locally to see how your updates appear in the documentation, run the command below in the root directory of this repository:

 $ python setup.py build_sphinx

The command above generates the user documentation and API documents under docs/html. Open docs/html/index.html in your Web browser to see how your updates appear in the documentation.

Note that docs/index.html is the top page of https://tmtsoftware.github.io/cont-pydocushare/, but it simply redirects to https://tmtsoftware.github.io/cont-pydocushare/html/index.html which is the substantial top page of PyDocuShare. The equivalent source file is docs/index.rst.

The above command sometimes does not work as intended due to remnant from the previous build. In that case, clean the build first:

 $ python setup.py clean
 $ python setup.py build_sphinx

See Release Procedure for more details about how to release the documents at https://tmtsoftware.github.io/cont-pydocushare/ .

Unit Test

PyDocuShare uses unittest unit testing framework. All test cases are stored under tests/. Execute the command below to run the unit tests:

 $ python -m unittest discover tests/ -vvv

You may notice that many test cases are skipped. This is because the command above tests only the functionality that does not require connection with a DocuShare site, which probably does not make sense. To test the main functionality of PyDocuShare, you need to provide your DocuShare connection information through environmental variables as follows:

DOCUSHARE_BASEURL : Base URL of your DocuShare site. For example, https://your.docushare.domain/docushare/ . It must end with a slash '/'.
DOCUSHARE_USERNAME: Your username of the DocuShare site.
DOCUSHARE_PASSWORD: [optional] Your password of the DocuShare site. Do not define this environmental variable to use stored password or have the unit test show the password prompt (recommended).
DOCUSHARE_VALID_DOCUMENT_HANDLE: Valid document handle like Document-12345.
DOCUSHARE_VALID_VERSION_HANDLE : Valid version handle like Version-111111.
DOCUSHARE_NOT_AUTHORIZED_DOCUMENT_HANDLE: Document handle like Document-12345 that the user is not authorized to access.
DOCUSHARE_NOT_AUTHORIZED_VERSION_HANDLE: Version handle like Version-111111 that the user is not authorized to access.

With those environmental variables, run the command above again. Now all test cases should have been executed.

The bash script below is the template to set all required environmental variables. Modify each value as appropriate.

# Base URL of your DocuShare site. It must end with a slash '/'.
export DOCUSHARE_BASEURL=https://your.docushare.domain/docushare/

# Your username of the DocuShare site.
export DOCUSHARE_USERNAME=your_user_name

# Valid document handle.
export DOCUSHARE_VALID_DOCUMENT_HANDLE=Document-12345

# Valid version handle.
export DOCUSHARE_VALID_VERSION_HANDLE=Version-111111

# Document handle like Document-54321 that the user is not authorized to access.
export DOCUSHARE_NOT_AUTHORIZED_DOCUMENT_HANDLE=Document-54321

# Version handle like Version-111111 that the user is not authorized to access.
export DOCUSHARE_NOT_AUTHORIZED_VERSION_HANDLE=Version-99999

Release Procedure

Follow the procedure below to release a new version.

Pre-release procedure
1. Make sure that you are in the main branch. If not, run git checkout main.
2. Make sure that all your local changes have been committed by git commit -a -m "your_commit_message".
3. Run all unit tests and confirm that all tests were passed.
4. Generate user documentation and API reference locally, make sure that there is no error or warning, and check the contents of the generated documents.
  - If the warning is known and you think you do not have to fix it, you may want to update nitpick_ignore or nitpick_ignore_regex variable in docs/conf.py.
Version tagging
1. Run git tag to see what is the latest version.
2. Run git tag -a vx.y.z -m "Version x.y.z" to mark the new release.
  - PyDocuShare uses setuptools-scm to automatically determine the version number from the git tags.
3. Run git push --tags. Make sure that you have --tags option to upload all tags to the upstream.
Release at https://test.pypi.org/
1. Install twine python packages if not yet. pip install twine.
2. Remove dist/ if exists.
3. Run python setup.py sdist.
4. Run twine upload --repository-url https://test.pypi.org/legacy/ dist/*.
5. Confirm that the version is available at https://test.pypi.org/project/PyDocuShare/ .
Release documentation
1. Run git checkout gh-pages to start working on the gh-pages branch.
2. Run git merge main to merge all changes made for the version to release.
3. Re-generate user documentation and API reference by running python setup.py clean and python setup.py build_sphinx --version x.y.z.
4. Run git add -f docs/html and git commit -m "Uploading documentation for version x.y.z.". These commands are supposed to commit all changes in the documentation under docs/html.
5. Run git push so that GitHub becomes aware of new documentation.
6. Confirm that the updated documentation is available at https://tmtsoftware.github.io/cont-pydocushare/ . Note that it may take a while (maybe a couple of minutes) until the updated documentation is available there.
7. Run git checkout main to make sure that you are back in the main branch for further development. Do not commit anything in the gh-pages branch except the new release documents.

TODO

Use "TODO" keyword in the inline comments in the source code and documentation to indicate things to be fixed in the future versions. The list below shows the major TODOs that are not suitable as inline comments:

Add unit tests for Collection handles and CollectionObject.
Add methods to upload files.
Upload the releases to PyPI.
Document more about the proper set-up of keyring.

tmtsoftware/cont-pydocushare