[CveXplore-278] doc restructure WIP #219

cve-search · Apr 18, 2024 · 8bad5dc · 8bad5dc
1 parent fb318b6
commit 8bad5dc
Show file tree

Hide file tree

Showing 6 changed files with 112 additions and 29 deletions.
diff --git a/CveXplore/main.py b/CveXplore/main.py
@@ -60,6 +60,13 @@ def _version():
 
 
 class CveXplore(object):
+    """
+    The CveXplore class is the main entry point for CveXplore. All functionality is available from straight from this
+    class or via the different subclasses / attributes.
+
+    Group:
+        Main
+    """
     def __init__(self, **kwargs):
         """
         Create a new instance of CveXplore
@@ -329,6 +336,12 @@ def get_single_store_entries(
            << Cves:CVE-2017-14445 >>,
            << Cves:CVE-2016-2354 >>]
 
+           >>> from CveXplore import CveXplore
+           >>> cvx = CveXplore()
+           >>> result = cvx.get_single_store_entries(("cves", {"cvss": {"$eq": 8}}), limit=0)
+           >>> len(result)
+           32
+
         Args:
             query: Tuple which contains the entry_type and the dict_filter in a tuple. Choices for entry_type:
 
@@ -422,18 +435,28 @@ def get_multi_store_entries(
         Method to perform *multiple* queries on *a single* or *multiple* collections in the data source and return the
         results.
 
-        A list of tuples which contains the entry_type and the dict_filter.
-            Choices for entry_type:
-                - capec;
-                - cpe;
-                - cwe;
-                - via4;
-                - cves;
+        Examples:
 
-            dict_filter is a dictionary representing a filter according to pymongo documentation.
+            >>> from CveXplore import CveXplore
+            >>> cvx = CveXplore()
+            >>> result = cvx.get_multi_store_entries([("CWE", {"id": "78"}), ("cves", {"id": "CVE-2009-0018"})])
+            >>> result
+            [<< Cwe:78 >>, << Cves:CVE-2009-0018 >>]
 
-            example:
-                get_multi_store_entries([("cwe", {"id": "78"}), ("cves", {"id": "CVE-2009-0018"})])
+        Args:
+            queries: A list of tuples which contains the entry_type and the dict_filter. Choices for entry_type:
+
+                    - capec;
+                    - cpe;
+                    - cwe;
+                    - via4;
+                    - cves;
+
+                    dict_filter is a dictionary representing a filter according to pymongo documentation.
+            limit: Limit the number of results to return.
+
+        Returns:
+            A list with CveXploreObject's or None
         """
 
         results = map(
@@ -456,7 +479,18 @@ def cves_for_cpe(self, cpe_string: str) -> List[CveXploreObject] | None:
         """
         Method for retrieving Cves that match a single CPE string. By default, the search will be made matching
         the configuration fields of the cves documents.
-        CPE string could be formatted like: ``cpe:2.3:o:microsoft:windows_7:*:sp1:*:*:*:*:*:*``
+
+        Examples:
+
+            >>> from CveXplore import CveXplore
+            >>> cvx = CveXplore()
+            >>> cves = cvx.cves_for_cpe("cpe:2.3:o:microsoft:windows_7:*:sp1:*:*:*:*:*:*")
+
+        Args:
+            cpe_string: CPE string to search for.
+
+        Returns:
+            A list with CveXploreObject's or None
         """
 
         cpe_regex_string = create_cpe_regex_string(cpe_string)
@@ -468,7 +502,16 @@ def cves_for_cpe(self, cpe_string: str) -> List[CveXploreObject] | None:
 
         return cves
 
-    def _validate_cve_id(self, cve_id: str):
+    def _validate_cve_id(self, cve_id: str) -> str:
+        """
+        Method for validating a CVE ID.
+
+        Args:
+            cve_id: The CVE ID to validate.
+
+        Returns:
+            A validated CVE ID.
+        """
         reg_match = re.compile(r"[cC][vV][eE]-\d{4}-\d{4,10}")
         if reg_match.match(cve_id) is not None:
             cve_id = cve_id.upper()
@@ -487,16 +530,26 @@ def _validate_cve_id(self, cve_id: str):
     def cve_by_id(self, cve_id: str) -> CveXploreObject | None:
         """
         Method to retrieve a single CVE from the database by its CVE ID number.
-        The number format should be either CVE-2000-0001, cve-2000-0001 or 2000-0001.
+
+        Args:
+            cve_id: The number format should be either CVE-2000-0001, cve-2000-0001 or 2000-0001.
+
+        Returns:
+            A CveXploreObject or None
         """
         cve_id = self._validate_cve_id(cve_id=cve_id)
 
         return self.get_single_store_entry("cves", {"id": cve_id})
 
     def cves_by_id(self, *cve_ids: str) -> Union[Iterable[CveXploreObject], Iterable]:
         """
-        Method to retrieve a multiple CVE's from the database by its CVE ID number.
-        The number format should be either CVE-2000-0001, cve-2000-0001 or 2000-0001.
+        Method to retrieve multiple CVE's from the database by their CVE ID numbers.
+
+        Args:
+            cve_ids: The number format should be either CVE-2000-0001, cve-2000-0001 or 2000-0001.
+
+        Returns:
+            A list with CveXploreObject's or empty list
         """
         ret_data = []
         for cve_id in cve_ids:
@@ -509,9 +562,14 @@ def cves_by_id(self, *cve_ids: str) -> Union[Iterable[CveXploreObject], Iterable
 
     def capec_by_cwe_id(self, cwe_id: int) -> List[CveXploreObject] | None:
         """
-        Method to retrieve capecs related to a specific CWE ID
-        """
+        Method to retrieve CAPEC's related to a specific CWE ID
 
+        Args:
+            cwe_id: The CWE ID to retrieve CAPEC for.
+
+        Returns:
+            A list with CveXploreObject's or None
+        """
         cwe = self.get_single_store_entry("cwe", {"id": cwe_id})
 
         if cwe is not None:
@@ -521,9 +579,14 @@ def capec_by_cwe_id(self, cwe_id: int) -> List[CveXploreObject] | None:
 
     def last_cves(self, limit: int = 10) -> List[CveXploreObject] | None:
         """
-        Method to retrieve the last entered / changed cves. By default, limited to 10.
-        """
+        Method to retrieve the last entered / changed cves.
+
+        Args:
+            limit: The amount of results to return; defaults to 10.
 
+        Returns:
+            A list with CveXploreObject's or None
+        """
         results = (
             getattr(self.datasource, "store_cves")
             .find()
@@ -540,10 +603,12 @@ def last_cves(self, limit: int = 10) -> List[CveXploreObject] | None:
 
     def get_db_content_stats(self) -> dict | str:
         """
-        Properties returning the stats from the database. Stats consist of the time last modified and the document count
+        This method request the statistics from the database and consist of the time last modified and the document count
         per cvedb store in the database.
-        """
 
+        Returns:
+            The stats from the database.
+        """
         stats = defaultdict(dict)
 
         if not isinstance(self.datasource, ApiDatabaseSource):
@@ -581,6 +646,11 @@ def get_db_content_stats(self) -> dict | str:
 
         return f"Using api endpoint: {self.datasource.baseurl}"
 
-    def __repr__(self):
-        """String representation of object"""
+    def __repr__(self) -> str:
+        """
+        String representation of object
+
+        Returns:
+            String representation of object
+        """
         return f"<< CveXplore:{self.version} >>"
diff --git a/README.rst b/README.rst
@@ -145,12 +145,12 @@ And to let CveXplore talk to an Cve Search API (only query POST endpoint needed)
    >>> cvx.version
    '0.1.2'
 
-For More options please check the full documentation
+For More options please check the package documentation
 
 Command line usage
 ------------------
 
-CveXplore has a 'Python Click' (`Documentation <https://click.palletsprojects.com/en/8.0.x/>`_) command line interpreter
+CveXplore has a 'Python Click' (`Documentation <https://click.palletsprojects.com/en/>`_) command line interpreter
 available. Click provides an extensive help function to guide you through the different options; also check the full
 documentation for examples and usage instructions
 

diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -20,8 +20,9 @@ a.reference.internal span.viewcode-link span.pre:hover,
     color: #b0eb00;
 }
 
-em.sig-param a.n.reference.internal span.n span.pre {
-    color: #ff9575;
+em.sig-param a.n.reference.internal span.n span.pre,
+dt[id^='p-'] span.n.sig-name {
+    color: #4567f1 !important;
     font-weight: normal;
 }
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -7,7 +7,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "CveXplore"
-copyright = "2024, Paul Tikken"
+copyright = "2020, Paul Tikken"
 author = "Paul Tikken"
 
 # -- General configuration ---------------------------------------------------
@@ -48,6 +48,10 @@
     (r".*\.__(str|repr)__", 5),
 ]
 
+python_type_aliases = {
+    "CveXplore.api.helpers.cve_search_api.ApiBaseClass": "ApiBaseClass",
+}
+
 python_apigen_order_tiebreaker = "alphabetical"
 
 rst_prolog = """

diff --git a/docs/package/code_base.rst b/docs/package/code_base.rst
@@ -1,4 +1,10 @@
 Code base
 ---------
 
+Main
+####
+.. python-apigen-group:: main
+
+Other
+#####
 .. python-apigen-group:: classes
diff --git a/docs/package/query_data.rst b/docs/package/query_data.rst
@@ -79,7 +79,9 @@ iterate over the requested results):
    ...
    << Capec:1 >>
 
-**WARNING The collection specific find method does not adhere to the default limit of 10**
+
+.. warning::
+    The collection specific find method does not adhere to the default limit of 10
 
 If you would limit (or sort / skip) the returned results you could append additional commands to your original query: