Migrate docs to mkdocs

README.md

@@ -110,18 +110,11 @@ to generate detailed code documentation automatically.
 To generate the documentation run the following:
 
 ```bash
-(venv) make html
+(venv) mkdocs serve
 python -m http.server 8000
 ```
 
-For live preview run:
-
-```bash
-(venv) make livehtml
-```
-
-Open the web browser and type `localhost:8000` as address. Or alternatively
-open `build/html/index.html` file in the web browser directly.
+Open the web browser and type `localhost:8000` as address.
 
 ## Checking Python style
 

docs/coreboot.md

@@ -0,0 +1,5 @@
+::: openness_score.coreboot
+    handler: python
+    options:
+        filters: []
+        docstring_style: sphinx

docs/source/design.rst → docs/design.md

@@ -1,11 +1,8 @@
-Dasharo Openness Score design
-=============================
+# Dasharo Openness Score design
 
 Dasharo Openness Score is designed following a few patterns and design rules.
 
-
-Dasharo Openness Score general rules
-------------------------------------
+## Dasharo Openness Score general rules
 
 1. The utility should not leave any intermediate files during the firmware
    image processing.
@@ -23,29 +20,28 @@ Dasharo Openness Score general rules
 
 3. The utility must be sa precise as possible to avoid falsified results.
 
-Dasharo Openness Score module design rules
-------------------------------------------
+## Dasharo Openness Score module design rules
 
 Each class representing a firmware image (or its integral part):
 
 1. Must calculate the 4 basic metrics (empty, data, closed-source and
    open-source) on the class instance creation.
-2. Should have a string method ``__str__`` which returns a set of 4 basic
+2. Should have a string method `__str__` which returns a set of 4 basic
    metrics and general attributes of the entity
-3. Should have a length method ``__len__`` which returns the size of the
+3. Should have a length method `__len__` which returns the size of the
    firmware image (or its integral part)
 4. Must contain attributes for the basic metrics using the following names:
-   ``self.open_code_size``, ``self.closed_code_size``, ``self.data_size`` and
-   ``self.empty_size``
-5. Must implement ``export_markdown`` method that will produce a markdown
+   `self.open_code_size`, `self.closed_code_size`, `self.data_size` and
+   `self.empty_size`
+5. Must implement `export_markdown` method that will produce a markdown
    report of the firmware image (or its integral part) statistics
-6. Must implement ``_calculate_metrics`` method which will perform the image
+6. Must implement `_calculate_metrics` method which will perform the image
    component classification and do the calculations
 7. Should implement a parse method which will perform the extraction of the
    image components and its attributes
-8. Must call the parse method and ``_calculate_metrics`` inside the class'
-  ``__init__`` method
-9. Must implement ``export_charts`` method to generate pie charts (only for
+8. Must call the parse method and `_calculate_metrics` inside the class'
+  `__init__` method
+9. Must implement `export_charts` method to generate pie charts (only for
    classes representing the whole firmware image)
 10. Must assume a component as closed-source if unable to classify to any
     category.

docs/index.md

@@ -0,0 +1,32 @@
+# Dasharo Openness Score
+
+## What is Dasharo Openness Score
+
+Have you ever wondered how open is your open-source firmware? How much
+closed-source and binary blobs is still there? Dasharo Openness Score utility
+answers those questions.
+
+Dasharo Openness is a report showing the open-source code to closed-source
+code ratio in the Dasharo firmware images. The results are also presented as a
+pie chart for better visual representation of the firmware image components
+and their share percentage.
+
+Dasharo Openness Score utility is capable of parsing Dasharo coreboot-based
+images as well as vendor UEFI images. Thanks to that one can easily compare
+how many bytes of the firmware have been liberated as well as by how much the
+Trusted Computing Base (TCB) has been reduced.
+
+Dasharo Openness Score utility not only support Dasharo coreboot-based images,
+but also many more coreboot distributions like heads.
+
+## How does it work?
+
+The utility leverages various tools like [coreboot's cbfstool][cbfstool] or
+[LongSoft's UEFIExtract][uefiextract] to decompose and parse the firmware
+images. The output from the utilities is used to detect the image type and then
+to calculate the openness metrics.
+
+For more details please refer to the [methodology document](./methodology.md)
+
+[cbfstool]: https://github.com/coreboot/coreboot/tree/master/util/cbfstool
+[uefiextract]: https://github.com/LongSoft/UEFITool