Merge pull request #164 from DeepSpace2/devel

devel to master - Furo docs theme

.readthedocs.yaml

@@ -1,5 +1,7 @@
 version: 2
 
+formats: all
+
 build:
   os: ubuntu-22.04
   tools:

docs/commandline_interface.rst

@@ -23,9 +23,14 @@ Usage
 Usage Examples
 ^^^^^^^^^^^^^^
 
-``$ styleframe --json_path data.json --output_path data.xlsx``
+.. code-block:: bash
+
+    $ styleframe --json_path data.json --output_path data.xlsx
+
+.. code-block:: bash
+
+    $ styleframe --json "[{\"sheet_name\": \"sheet_1\", \"columns\": [{\"col_name\": \"col_a\", \"cells\": [{\"value\": 1}]}]}]"
 
-``$ styleframe --json "[{\"sheet_name\": \"sheet_1\", \"columns\": [{\"col_name\": \"col_a\", \"cells\": [{\"value\": 1}]}]}]"``
 
 .. note:: You may need to use different syntax to pass a JSON string depending on your OS and terminal application.
 

docs/conf.py

@@ -4,15 +4,34 @@
 sys.path.insert(0, os.path.abspath('..'))
 
 add_module_names = False
+
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
+    'sphinx.ext.viewcode',
+    'sphinx_copybutton'
 ]
-html_theme = "sphinx_rtd_theme"
+
+html_theme = 'furo'
+
+html_theme_options = {
+    "source_repository": "https://github.com/DeepSpace2/styleframe/",
+    "source_branch": "devel",
+    "source_directory": "docs/",
+    "dark_css_variables": {
+        "color-api-name": "#2b8cee"
+    },
+    "light_css_variables": {
+        "color-api-name": "#2962ff"
+    }
+}
+
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3', None),
     'pandas': ('https://pandas.pydata.org/docs/', None),
     'numpy': ('https://numpy.org/doc/stable/', None)
 }
+
 master_doc = 'index'
+
 project = 'styleframe'

docs/installation.rst

@@ -1,10 +1,13 @@
 Installation and testing
 ========================
 
-``$ pip install styleframe``
+.. code-block:: bash
+
+    $ pip install styleframe
 
 To make sure everything works as expected, run styleframe's unittests:
-::
+
+.. code-block:: python
 
    from styleframe import tests
 

docs/requirements.txt

@@ -1,7 +1,8 @@
+furo
 openpyxl>=2.5,<4
 colour>=0.1.5,<0.2
 jsonschema
 pandas<3
 xlrd>=1.0.0,<1.3.0 ; python_version<='3.6'
 sphinx==7.2.6
-sphinx-rtd-theme
+sphinx-copybutton

docs/usage_examples.rst

@@ -3,7 +3,8 @@ Basic Usage Examples
 
 StyleFrame's ``init`` supports all the ways you are used to initiate pandas dataframe.
 An existing dataframe, a dictionary or a list of dictionaries:
-::
+
+.. code-block:: python
 
     from styleframe import StyleFrame, Styler, utils
 
@@ -12,25 +13,36 @@ An existing dataframe, a dictionary or a list of dictionaries:
 Applying a style to rows that meet a condition using pandas selecting syntax.
 In this example all the cells in the `col_a` column with the value > 50 will have
 blue background and a bold, sized 10 font:
-::
 
+.. code-block:: python
 
-    sf.apply_style_by_indexes(indexes_to_style=sf[sf['col_a'] > 50],
-                              cols_to_style=['col_a'],
-                              styler_obj=Styler(bg_color=utils.colors.blue, bold=True, font_size=10))
+    sf.apply_style_by_indexes(
+        indexes_to_style=sf[sf['col_a'] > 50],
+        cols_to_style=['col_a'],
+        styler_obj=Styler(
+            bg_color=utils.colors.blue,
+            bold=True,
+            font_size=10
+        )
+    )
 
 Creating ExcelWriter object:
-::
+
+.. code-block:: python
 
     ew = StyleFrame.ExcelWriter(r'C:\my_excel.xlsx')
     sf.to_excel(ew)
     ew.close()
 
 It is also possible to style a whole column or columns, and decide whether to style the headers or not:
-::
 
-    sf.apply_column_style(cols_to_style=['a'], styler_obj=Styler(bg_color=utils.colors.green),
-                          style_header=True)
+.. code-block:: python
+
+    sf.apply_column_style(
+        cols_to_style=['a'],
+        styler_obj=Styler(bg_color=utils.colors.green),
+        style_header=True
+    )
 
 Accessors
 ---------
@@ -39,7 +51,8 @@ Accessors
 ^^^^^^
 
 Combined with `.loc`, allows easy selection/indexing based on style. For example:
-::
+
+.. code-block:: python
 
     only_rows_with_yellow_bg_color = sf.loc[sf['col_name'].style.bg_color == utils.colors.yellow]
     only_rows_with_non_bold_text = sf.loc[~sf['col_name'].style.bold]

styleframe/style_frame.py

@@ -171,7 +171,7 @@ def read_excel(cls, path: str, sheet_name: Union[str, int] = 0, read_style: bool
 
             .. note:: Using ``use_openpyxl_styles=False`` is useful if you are going to filter columns or rows by style, for example:
 
-                     ::
+                     .. code-block:: python
 
                         sf = sf[[col for col in sf.columns if col.style.font == utils.fonts.arial]]
 
@@ -383,7 +383,7 @@ def to_excel(self, excel_writer: Union[str, pd.ExcelWriter, pathlib.Path] = 'out
                       column. However this isn't guaranteed to work for all fonts (works best with monospaced fonts). The formula
                       used to calculate a column's width is equivalent to
 
-                      ::
+                      .. code-block:: python
 
                         (len(longest_value_in_column) + A_FACTOR) * P_FACTOR
 
@@ -617,7 +617,7 @@ def apply_style_by_indexes(self,
         :param indexes_to_style: Indexes to which the provided style will be applied.
             Usually passed as pandas selecting syntax. For example,
 
-            ::
+            .. code-block:: python
 
                 sf[sf['some_col'] == 20]
 

styleframe/styler.py

@@ -301,13 +301,13 @@ def combine(cls, *styles: 'Styler'):
         Used to combine :class:`Styler` objects. The right-most object has precedence.
         For example:
 
-        ::
+        .. code-block:: python
 
             Styler.combine(Styler(bg_color='yellow', font_size=24), Styler(bg_color='blue'))
 
         will return
 
-        ::
+        .. code-block:: python
 
             Styler(bg_color='blue', font_size=24)