chg: add docstrings and extend conf.py for RTD

Add minimal docstrings to public methods so ReadTheDocs will display them.
Add autodoc mock import for lief so RTD can generate HTML for tools.

This fixes issue #626

.gitignore

@@ -1,6 +1,7 @@
 *.swp
 *.pem
 *.pyc
+docs/build/
 examples/keys.py
 examples/cudeso.py
 examples/feed-generator/output/*\.json

README.md

@@ -1,7 +1,6 @@
-**IMPORTANT NOTE**: This library will require **at least** python 3.6 starting the 1st of January 2020. If you have to legacy versions of python, please use PyMISP v2.4.119.1, and consider updating your system(s). Anything released within the last 2 years will do, starting with Ubuntu 18.04.
+**IMPORTANT NOTE**: This library will require **at least** python 3.6 starting the 1st of January 2020. If you have legacy versions of python, please use PyMISP v2.4.119.1, and consider updating your system(s). Anything released within the last 2 years will do, starting with Ubuntu 18.04.
 
-README
+# PyMISP - Python Library to access MISP
-======
 
 [![Documentation Status](https://readthedocs.org/projects/pymisp/badge/?version=latest)](http://pymisp.readthedocs.io/?badge=latest)
 [![Build Status](https://travis-ci.org/MISP/PyMISP.svg?branch=main)](https://travis-ci.org/MISP/PyMISP)
@@ -10,8 +9,6 @@ README
 [![PyPi version](https://img.shields.io/pypi/v/pymisp.svg)](https://pypi.python.org/pypi/pymisp/)
 [![Number of PyPI downloads](https://img.shields.io/pypi/dm/pymisp.svg)](https://pypi.python.org/pypi/pymisp/)
 
-# PyMISP - Python Library to access MISP
-
 PyMISP is a Python library to access [MISP](https://github.com/MISP/MISP) platforms via their REST API.
 
 PyMISP allows you to fetch events, add or update events/attributes, add or update samples or search for attributes.
@@ -34,7 +31,7 @@ pip3 install pymisp[fileobjects,openioc,virustotal]
 
 ## Install the latest version from repo from development purposes
 
-**Note**: poetry is required
+**Note**: poetry is required; e.g., "pip3 install poetry"
 
 ```
 git clone https://github.com/MISP/PyMISP.git && cd PyMISP
@@ -83,7 +80,7 @@ python3 last.py -l 45m # 45 minutes
 
 ## Debugging
 
-You have two options there:
+You have two options here:
 
 1. Pass `debug=True` to `PyMISP` and it will enable logging.DEBUG to stderr on the whole module
 
@@ -94,7 +91,7 @@ You have two options there:
 import logging
 logger = logging.getLogger('pymisp')
 
-# Configure it as you whish, for example, enable DEBUG mode:
+# Configure it as you wish, for example, enable DEBUG mode:
 logger.setLevel(logging.DEBUG)
 ```
 
@@ -111,7 +108,7 @@ logging.basicConfig(level=logging.DEBUG, filename="debug.log", filemode='w', for
 ## Test cases
 
 1. The content of `mispevent.py` is tested on every commit
-2. The tests cases that require a running MISP instance can be run the following way:
+2. The test cases that require a running MISP instance can be run the following way:
 
 
 ```bash
@@ -133,13 +130,13 @@ A series of [Jupyter notebooks for PyMISP tutorial](https://github.com/MISP/PyMI
 
 ... or at least everything that can be imported/exported from/to a json blob
 
-`AbstractMISP` is the master class, and inherit `collections.MutableMapping` which means
+`AbstractMISP` is the master class, and inherits from `collections.MutableMapping` which means
 the class can be represented as a python dictionary.
 
 The abstraction assumes every property that should not be seen in the dictionary is prepended with a `_`,
 or its name is added to the private list `__not_jsonable` (accessible through `update_not_jsonable` and `set_not_jsonable`.
 
-This master class has helpers that will make it easy to load, and export, to, and from, a json string.
+This master class has helpers that make it easy to load, and export to, and from, a json string.
 
 `MISPEvent`, `MISPAttribute`, `MISPObjectReference`, `MISPObjectAttribute`, and `MISPObject`
 are subclasses of AbstractMISP, which mean that they can be handled as python dictionaries.
@@ -148,6 +145,6 @@ are subclasses of AbstractMISP, which mean that they can be handled as python di
 
 Creating a new MISP object generator should be done using a pre-defined template and inherit `AbstractMISPObjectGenerator`.
 
-Your new MISPObject generator need to generate attributes, and add them as class properties using `add_attribute`.
+Your new MISPObject generator must generate attributes and add them as class properties using `add_attribute`.
 
 When the object is sent to MISP, all the class properties will be exported to the JSON export.

docs/source/conf.py

@@ -40,6 +40,7 @@ extensions = [
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',
     'sphinx.ext.imgconverter',
+    'recommonmark',
 ]
 
 napoleon_google_docstring = False
@@ -132,6 +133,9 @@ pygments_style = 'sphinx'
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
+# lief is a bit difficult to install
+autodoc_mock_imports = ["lief"]
+
 
 # -- Options for HTML output ----------------------------------------------
 

docs/source/index.rst

@@ -9,7 +9,7 @@ Welcome to PyMISP's documentation!
 Contents:
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 2
 
    README
    modules

docs/source/modules.rst

@@ -1,5 +1,5 @@
-pymisp
+pymisp - Modules
-======
+================
 
 .. toctree::
    :maxdepth: 4

pymisp/mispevent.py

@@ -1030,8 +1030,7 @@ class MISPEvent(AbstractMISP):
 
     def to_feed(self, valid_distributions: List[int] = [0, 1, 2, 3, 4, 5], with_meta: bool = False) -> Dict:
         """ Generate a json output for MISP Feed.
-        Notes:
+        Note: valid_distributions only makes sense if the distribution key is set; i.e., the event is exported from a MISP instance.
-            * valid_distributions only makes sense if the distribution key is set (i.e. the event is exported from a MISP instance)
         """
         required = ['info', 'Orgc']
         for r in required: