Fix more documentation issues (#12)

* fix some documentation issues
* update history, version bump

CONTRIBUTING.rst

@@ -1,4 +1,5 @@
 .. highlight:: shell
+.. _contributing_label:
 
 ============
 Contributing
@@ -7,6 +8,9 @@ Contributing
 Contributions are welcome, and they are greatly appreciated! Every little bit
 helps, and credit will always be given.
 
+We would appreciate a feature suggestion issue before you create a PR so we can
+discuss the feature, its use, and its implementation.
+
 You can contribute in many ways:
 
 Types of Contributions
@@ -107,18 +111,19 @@ Tips
 
 To run a subset of tests::
 
- $ py.test tests.test_jointly
+ $ py.test tests/test_examples.py
 
 
 To run all tests::
 
- $ py.test tests.test_jointly
+ $ py.test
 
 Deploying
 ---------
 
 A reminder for the maintainers on how to deploy.
 Make sure all your changes are committed, including an entry in HISTORY.rst and an update of the old version code
 in ``docs/conf.py`` and ``pyproject.toml``.
+Please also link the PR in your history entry.
 
 GitHub will then deploy to PyPI if tests pass.

HISTORY.rst

@@ -2,6 +2,13 @@
 History
 =======
 
+1.0.4 (2021-12-27)
+------------------
+
+* fix contributing.rst guide to testing
+* improve documentation problems
+* c.f. https://github.com/hpi-dhc/jointly/pull/12
+
 1.0.3 (2021-12-09)
 ------------------
 

README.rst

@@ -54,6 +54,8 @@ Install the package from pypi:
 
  pip install jointly
 
+You might want to check out our :ref:`contributing_label` guide in case you want to edit the package.
+
 Usage
 -----
 

docs/reference.rst

@@ -43,6 +43,14 @@ jointly.helpers
  :undoc-members:
  :show-inheritance:
 
+jointly.helpers_plotting
+---------------
+
+.. automodule:: jointly.helpers_plotting
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
 jointly.abstract\_extractor
 ---------------------------
 
@@ -59,12 +67,3 @@ jointly.log
  :members:
  :undoc-members:
  :show-inheritance:
-
-
-jointly.segment\_selector
--------------------------
-
-.. automodule:: jointly.segment_selector
- :members:
- :undoc-members:
- :show-inheritance:

jointly/helpers.py

@@ -1,4 +1,4 @@
-"""Contains plotting helpers"""
+"""Contains various helper functions useful in conjunction with or internally to jointly."""
 import logging
 from pprint import pprint
 from typing import List, Tuple, Iterable
@@ -15,7 +15,12 @@
 def calculate_magnitude(
  df: pd.DataFrame, of_cols: List[str], title: str = "Magnitude"
 ) -> pd.DataFrame:
- """Calculate the magnitude of a subset of columns from a DataFrame"""
+ """
+ Calculate the magnitude of a subset of columns from a DataFrame.
+
+ Will return 0 if the input data is NaN to allow future algorithms
+ to continue working despite the NaN in the input values.
+ """
  data = df[of_cols]
  result = np.sqrt(np.square(data).sum(axis=1))
  result.name = title
@@ -107,6 +112,9 @@ def get_stretch_factor(
  Get the stretch factor required to stretch the duration between segments such that it will fit exactly to the
  signal when shifted by the amount given by timeshifts.
 
+ This is a function that should basically exclusively be used within jointly, as the parameters are produced during
+ the synchronization process.
+
  :param segments: the segment instance containing the segment info to be stretched
  :param timeshifts: the timeshifts that should be applied to make the signal align to the reference signal
  :return: a float as described above
@@ -135,6 +143,10 @@ def verify_segments(signals: Iterable[str], segments: SyncPairs):
 def get_segment_data(
  dataframe: pd.DataFrame, segments: SyncPairs, col: str, segment: str
 ) -> Tuple[pd.Timestamp, pd.Timestamp, pd.DataFrame]:
+ """
+ Return a 3-tuple of start and end indices plus data
+ within that timeframe of the given column in the given dataframe.
+ """
  start = segments[col][segment]["start"]
  end = segments[col][segment]["end"]
  return start, end, dataframe[col][start:end]

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "jointly"
-version = "1.0.3"
+version = "1.0.4"
 description = "Synchronize sensor data from accelerometer shakes"
 authors = [
  "Ariane Morassi Sasso <ariane.morassi-sasso@hpi.de>",