Merge pull request #629 from chrisinmtown/fix-api-doc-params

Fix api doc params

.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: