refactor: rename pkg to pyBiocFileCache, use markdown for documentation

Author: jkanche

.coveragerc

@@ -1,7 +1,7 @@
 # .coveragerc to control coverage.py
 [run]
 branch = True
-source = pybioccache
+source = pybiocfilecache
 # omit = bad_file.py
 
 [paths]

AUTHORS.rst renamed to AUTHORS.md

@@ -1,5 +1,3 @@
-============
-Contributors
-============
+# Contributors
 
 * jkanche <jayaram.kancherla@gmail.com>

CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## Version 0.1 (development)
+
+- Initial release

CHANGELOG.rst

@@ -27,7 +27,7 @@
 Contributing
 ============
 
-Welcome to ``pyBiocCache`` contributor's guide.
+Welcome to ``pyBiocFileCache`` contributor's guide.
 
 This document focuses on getting any potential contributor familiarized
 with the development processes, but `other kinds of contributions`_ are also
@@ -46,7 +46,7 @@ guidelines.
 Issue Reports
 =============
 
-If you experience bugs or general issues with ``pyBiocCache``, please have a look
+If you experience bugs or general issues with ``pyBiocFileCache``, please have a look
 on the `issue tracker`_. If you don't see anything useful there, please feel
 free to fire an issue report.
 
@@ -65,10 +65,10 @@ you help us to identify the root cause of the issue.
 Documentation Improvements
 ==========================
 
-You can help improve ``pyBiocCache`` docs by making them more readable and coherent, or
+You can help improve ``pyBiocFileCache`` docs by making them more readable and coherent, or
 by adding missing information and correcting mistakes.
 
-``pyBiocCache`` documentation uses Sphinx_ as its main documentation compiler.
+``pyBiocFileCache`` documentation uses Sphinx_ as its main documentation compiler.
 This means that the docs are kept in the same repository as the project code, and
 that any documentation update is done in the same way was a code contribution.
 
@@ -80,7 +80,7 @@ that any documentation update is done in the same way was a code contribution.
 
    .. tip::
       Please notice that the `GitHub web interface`_ provides a quick way of
-      propose changes in ``pyBiocCache``'s files. While this mechanism can
+      propose changes in ``pyBiocFileCache``'s files. While this mechanism can
       be tricky for normal code contributions, it works perfectly fine for
       contributing to the docs, and can be quite handy.
 
@@ -142,8 +142,8 @@ Clone the repository
    page. This creates a copy of the code under your account on |the repository service|.
 #. Clone this copy to your local disk::
 
-    git clone git@github.com:YourLogin/pyBiocCache.git
-    cd pyBiocCache
+    git clone git@github.com:YourLogin/pyBiocFileCache.git
+    cd pyBiocFileCache
 
 #. You should run::
 
@@ -158,7 +158,7 @@ Clone the repository
     pip install pre-commit
     pre-commit install
 
-   ``pyBiocCache`` comes with a lot of hooks configured to automatically help the
+   ``pyBiocFileCache`` comes with a lot of hooks configured to automatically help the
    developer to check the code being written.
 
 Implement your changes
@@ -285,7 +285,7 @@ Releases
 
 If you are part of the group of maintainers and have correct user permissions
 on PyPI_, the following steps can be used to release a new version for
-``pyBiocCache``:
+``pyBiocFileCache``:
 
 #. Make sure all unit tests are successful.
 #. Tag the current commit on the main branch with a release tag, e.g., ``v1.2.3``.
@@ -314,8 +314,8 @@ on PyPI_, the following steps can be used to release a new version for
 .. |the repository service| replace:: GitHub
 .. |contribute button| replace:: "Create pull request"
 
-.. _repository: https://github.com/<USERNAME>/pyBiocCache
-.. _issue tracker: https://github.com/<USERNAME>/pyBiocCache/issues
+.. _repository: https://github.com/<USERNAME>/pyBiocFileCache
+.. _issue tracker: https://github.com/<USERNAME>/pyBiocFileCache/issues
 .. <-- end -->
 
 

CONTRIBUTING.rst

@@ -0,0 +1,71 @@
+# pyBiocFileCache
+
+An attempt at the Python implementation of 
+the [BiocFileCache R package](https://github.com/Bioconductor/BiocFileCache)
+
+Note: Package is in development. Use with caution!!
+
+
+
+
+## Description
+
+#### Create a cache directory 
+
+```
+from pyBiocCache import BiocFileCache
+import os
+
+bfc = BiocFileCache(cache_dir = os.getcwd() + "/cache")
+```
+
+Once the cache directory is created, the library allows
+- Create a resource - `add`
+- Get a resource from cache - `get`
+- Remove a resource - `remove`
+- update a resource - `update`
+- purge the entire cache - `purge`
+
+#### Add a resource to cache
+
+(for testing use the temp files in the `tests/data` directory)
+
+```
+rec = bfc.add("test1", os.getcwd() + "/test1.txt")
+print(rec)
+```
+
+#### Get resource from cache
+
+```
+rec = bfc.get("test1")
+print(rec)
+```
+
+#### Remove resource from cache
+
+```
+rec = bfc.remove("test1")
+print(rec)
+```
+
+#### Update resource in cache
+
+```
+rec = bfc.get("test1"m os.getcwd() + "test2.txt")
+print(rec)
+```
+
+#### purge the cache
+
+```
+bfc.purge()
+```
+
+
+<!-- pyscaffold-notes -->
+
+## Note
+
+This project has been set up using PyScaffold 4.1. For details and usage
+information on PyScaffold see https://pyscaffold.org/.

README.md

@@ -0,0 +1 @@
+../AUTHORS.md

README.rst

@@ -0,0 +1 @@
+../CHANGELOG.md

docs/authors.md

@@ -34,7 +34,7 @@
     from sphinx import apidoc
 
 output_dir = os.path.join(__location__, "api")
-module_dir = os.path.join(__location__, "../src/pybioccache")
+module_dir = os.path.join(__location__, "../src/pybiocfilecache")
 try:
     shutil.rmtree(output_dir)
 except FileNotFoundError:
@@ -77,8 +77,29 @@
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
+
+# Configure AutoStructify
+# https://recommonmark.readthedocs.io/en/latest/auto_structify.html
+def setup(app):
+    from recommonmark.transform import AutoStructify
+
+    params = {
+        "enable_auto_toc_tree": True,
+        "auto_toc_tree_section": "Contents",
+        "auto_toc_maxdepth": 2,
+        "enable_eval_rst": True,
+        "enable_math": True,
+        "enable_inline_math": True,
+    }
+    app.add_config_value("recommonmark_config", params, True)
+    app.add_transform(AutoStructify)
+
+
+# Enable markdown
+extensions.append("recommonmark")
+
 # The suffix of source filenames.
-source_suffix = ".rst"
+source_suffix = [".rst", ".md"]
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
@@ -87,7 +108,7 @@
 master_doc = "index"
 
 # General information about the project.
-project = "pyBiocCache"
+project = "pyBiocFileCache"
 copyright = "2021, jkanche"
 
 # The version info for the project you're documenting, acts as replacement for
@@ -99,7 +120,7 @@
 # If you don’t need the separation provided between version and release,
 # just set them both to the same value.
 try:
-    from pybioccache import __version__ as version
+    from pybiocfilecache import __version__ as version
 except ImportError:
     version = ""
 
@@ -229,7 +250,7 @@
 # html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = "pyBiocCache-doc"
+htmlhelp_basename = "pyBiocFileCache-doc"
 
 
 # -- Options for LaTeX output ------------------------------------------------
@@ -246,7 +267,7 @@
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-    ("index", "user_guide.tex", "pyBiocCache Documentation", "jkanche", "manual")
+    ("index", "user_guide.tex", "pyBiocFileCache Documentation", "jkanche", "manual")
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -283,4 +304,4 @@
     "pyscaffold": ("https://pyscaffold.org/en/stable", None),
 }
 
-print(f"loading configurations for {project} {version} ...", file=sys.stderr)
+print(f"loading configurations for {project} {version} ...", file=sys.stderr)

docs/authors.rst

@@ -0,0 +1,38 @@
+# pyBiocFileCache
+
+Add a short description here!
+
+
+## Note
+
+> This is the main page of your project's [Sphinx] documentation. It is
+> formatted in [Markdown]. Add additional pages by creating md-files in
+> `docs` or rst-files (formated in [reStructuredText]) and adding links to
+> them in the `Contents` section below.
+>
+> Please check [Sphinx], [recommonmark] and [autostructify] for more information
+> about how to document your project and how to configure your preferences.
+
+
+## Contents
+
+* [Overview](readme)
+* [License](license)
+* [Authors](authors)
+* [Changelog](changelog)
+* [Module Reference](api/modules)
+
+
+## Indices and tables
+
+```eval_rst
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+```
+
+[Sphinx]: http://www.sphinx-doc.org/
+[Markdown]: https://daringfireball.net/projects/markdown/
+[reStructuredText]: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+[recommonmark]: https://recommonmark.readthedocs.io/en/latest
+[autostructify]: https://recommonmark.readthedocs.io/en/latest/auto_structify.html