Merge pull request #12 from MunchLab/Updating-contributing-documentation

Lots of cleanup, linting, documentation, especially contributing section

.github/pull_request_template.md

@@ -21,9 +21,9 @@
 ## Checklist
 <!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
 <!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
-- [ ] My code follows the code style of this project.
+- [ ] My code follows the code style of this project. (`make clean`)
 - [ ] My change requires a change to the documentation.
-- [ ] I have updated the documentation accordingly.
+- [ ] I have updated the documentation accordingly. (`make tests`)
 - [ ] I have incremented the version number in the `pyproject.toml` file.
 - [ ] I have added tests to cover my changes.
-- [ ] All new and existing tests passed.
+- [ ] All new and existing tests passed. (`make tests`)

Makefile

@@ -31,26 +31,11 @@ html:
 	rm -r docs/html
 
 all:
-	# Cleaning build folder
-	@mkdir $(shell pwd)/build/temp
-	@rm -rf $(shell pwd)/build/
-	@mkdir $(shell pwd)/build/
-
-	# Cleaning docs folder
-	@mkdir $(shell pwd)/docs/temp
-	@rm -rf $(shell pwd)/docs/
-	@mkdir $(shell pwd)/docs/
-
-	# Running sphinx-build to build html files.
-	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-	# Copying over contents of build/html to docs
-	@mkdir $(shell pwd)/docs/.doctrees
-	@cp -a $(shell pwd)/build/doctrees/. $(shell pwd)/docs/.doctrees/
-	@cp -a $(shell pwd)/build/html/. $(shell pwd)/docs/
-
 	# Running autopep8
-	@autopep8 -r --in-place ect/
+	@make clean
+
+	# Generate documentation 
+	@make html
 
 	# Running unittests
-	@python -m unittest
+	@make tests

doc_source/citing.rst

@@ -0,0 +1,7 @@
+Citing
+=======
+
+To cite `ect` please use the following publication:
+
+   Elizabeth Munch. An Invitation to the Euler Characteristic Transform. `arXiv:2310.10395 <https://arxiv.org/abs/2310.10395>`_. 2023.
+

doc_source/conf.py

@@ -28,22 +28,32 @@
 author = 'MunchLab'
 
 # The full version, including alpha/beta/rc tags
-release = '0.0.1'
+release = '0.1.3'
 
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [ 'myst_parser', 
-              "sphinx.ext.githubpages",
+extensions = ['sphinx.ext.autodoc',
+            #   'numpydoc',
+              'sphinx.ext.coverage',
+              'sphinx.ext.napoleon',
+              'matplotlib.sphinxext.mathmpl',
+              'matplotlib.sphinxext.plot_directive',
+              'sphinx.ext.autosummary',
+              'sphinx.ext.doctest',
+              'sphinx.ext.intersphinx',
+              'sphinx.ext.todo',
               'sphinx.ext.mathjax',
-              "sphinx.ext.autodoc",
-                "sphinx.ext.autosummary",
-                # "myst_nb"
-                "nbsphinx"
-]
+              'sphinx.ext.ifconfig',
+              'sphinx.ext.viewcode',
+              'sphinx.ext.githubpages',
+              'myst_parser', 
+              'sphinx.ext.autosummary',
+              'nbsphinx',
+              'sphinx.ext.viewcode']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -60,6 +70,15 @@
 # a list of builtin themes.
 #
 html_theme = 'sphinx_rtd_theme'
+autodoc_default_options = {
+    'members': True,
+    'member-order': 'bysource',
+    'special-members': '__init__',
+    'undoc-members': True,
+    'exclude-members': '__weakref__'
+}
+numpydoc_show_class_members = False
+autodoc_typehints = "none"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

doc_source/contributing.rst

@@ -0,0 +1,122 @@
+Contributing to the `ect` Package
+=================================
+
+*Note this is a draft document and is subject to change.*
+
+Getting Started
+---------------
+
+- Prerequisites
+- Setting up the development environment
+- Forking the `ect` repository
+- Cloning the repository
+
+Contributing Guidelines
+-----------------------
+
+Code style and formatting
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is essential for this project to have well documented, clean, and readable code. The following guidelines should be followed when contributing to the `ect` package:
+
+- Use the PEP 8 style guide for Python code.
+- Follow docstring format given below for documenting functions and classes.
+- Use the Sphinx documentation system for generating documentation.
+- Always include tests for new features and bug fixes.
+
+
+Documentation guidelines
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The `ect` package uses the Sphinx documentation system for generating documentation. There are two things to be doing when contributing to the documentation:
+
+- First, include docstrings in the code which will be autogenerated into the documentation. When in doubt, write too much. 
+- Second, write documentation in the `doc_source` directory using the reStructuredText format. This package also supports writing files in markdown, although there are some issues when dealing with autogenerated content so it's a bit of a mix at the moment. Note that when the documentation is generated, everything in the `docs` folder is deleted and overwritten, so do not do your work in there, it will be lost!
+
+Assuming everything (TODO: Add install list) is set up correctly, you can generate the documentation by running the following command from the top level folder::
+    
+    make html
+
+This will generate the documentation in the ``docs`` directory. You can view the documentation by opening the ``docs/index.html`` file in your browser.
+
+An example of a docstring for a function is given below. Note the use of indentation since rst is picky about it::
+
+    def my_function(arg1, arg2):
+        """
+        This is a brief description of the function.
+
+        This is a more detailed description of the function. It should include
+        information about the arguments and the return value. If the function
+        raises any exceptions, they should be documented here as well. Math can be included in text by using the math directive, e.g. :math:`y = x^2`. A displayed equation can be added as well using the math block directive. Note that for certain letters that are reserved by rst, you need to escape them with a backslash, e.g. `\\f` in the code below.
+                
+            .. math::
+
+                \int_0^1 x^2 dx = \\frac{1}{3}
+        
+        Code blocks can also be included using the code-block directive:
+        
+            .. code-block:: python
+    
+                def my_function(arg1, arg2):
+                    return arg1 + arg2
+        
+        Just ending a sentence with two colons also will create a code block::
+            
+                def my_function(arg1, arg2):
+                    return arg1 + arg2
+
+        Parameters
+        ----------
+        arg1 (type):
+            Description of arg1.
+        arg2 (type):
+            Description of arg2.
+
+        Returns
+        -------
+        type
+            Description of the return value.
+
+        Raises
+        ------
+        ExceptionType
+            Description of when this exception is raised.
+        """
+
+
+
+Testing guidelines
+^^^^^^^^^^^^^^^^^^
+
+You should always include tests for new features and bug fixes. The `ect` package uses the `pytest` testing framework. The tests are located in the `tests` directory. To run the tests, you can use the following command::
+
+    pytest
+
+or the standard `unittest` python framework by running::
+
+    make tests
+
+Get in the habit of writing lots of simple tests. It is better to have too many tests than too few. The tests should be written in a way that they can be run quickly and easily. This will make it easier for you to test your code as you develop it and for others to test your code when they review it. Take a look at the existing tests for examples. 
+
+Note that in order for a function written in the test folder to be run, the function must be prefixed with `test_`. For example, a test function for a function called `my_function` would be called `test_my_function`. 
+
+Issue tracking and pull requests
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you find an issue, please post it on the `GitHub issue tracker <https://github.com/MunchLab/ect/issues>`. Provide as much information as possible, including the version of the `ect` package you are using, the operating system you are using, and any other relevant information.
+
+If you would like to fix an issue and you are a contributor to the project, please create a new branch for the fix. Note that the ``main`` branch is protected so you will not be able to push directly to that branch. Once you are ready to open discussion, you will create a pull request. The pull request should include a description of the issue and the fix. There is a template for pull requests that you can use to fill out helpful information. 
+
+- Note that in order for the `pip install` command to work, the version number in the `pyproject.toml` file must be updated.
+- You should also make sure to update the version number to match in the ``doc_source/conf.py`` file. This will ensure that the documentation is updated with the correct version number.
+- Be sure to run ``make all`` before committing to ensure that the code is cleaned, the documentation is up to date, and the tests all pass.
+
+If you are not a contributor, you will need to fork the code and create a pull request from your fork.
+Note that all pull requests need to be approved by Liz Munch before they can be merged. 
+
+Conclusion
+----------
+
+- Acknowledgements
+- Future development plans
+- Contact information and support

doc_source/index.rst

@@ -7,16 +7,16 @@ Table of Contents
 -----------------
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :numbered:
    :caption: Contents:
 
-   Getting Started <installation.md>
+   Getting Started <installation.rst>
    Modules <modules.rst>
    Tutorials <tutorials.md>
-   Contributing <contributing.md>
+   Contributing <contributing.rst>
    License <license.md>
-   Citing <citing.md>
+   Citing <citing.rst>
 
 Description
 -----------

doc_source/installation.rst

@@ -0,0 +1,37 @@
+Installation
+============
+
+Prerequisites
+-------------
+
+Before installing `ect`, make sure you have the following prerequisites:
+
+- Python (version 3.7 or higher)
+- Pip (Python package installer)
+
+Installing `ect`
+----------------
+
+To install `ect`, run the following in a terminal.
+
+.. code-block:: bash
+
+    pip install ect
+
+Alternatively, you can install directly from the source by cloning the repository and running the following command:
+
+.. code-block:: bash
+
+    git clone https://github.com/MunchLab/ect
+    cd ect
+    pip install .
+
+
+Uninstalling `ect`
+------------------
+
+To uninstall `ect`, simply run the following command:
+
+.. code-block:: bash
+
+    pip uninstall ect

doc_source/modules.rst

@@ -5,5 +5,5 @@ Table of Contents
    :maxdepth: 2
 
 
-   ECT on graphs <ect_on_graphs.md>
-   Embedded graphs <embed_graph.md>
+   Embedded graphs <embed_graph.md>
+   ECT on graphs <ect_on_graphs.md>

docs/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: e5078083e1e4dc0826581f131d0ee9a3
+config: 323577bb763e1ae020bcf349ad4827a5
 tags: 645f666f9bcd5a90fca523b33c5a78b7