diff --git a/.readthedocs.yaml b/.readthedocs.yaml index e88e6c7..ffcb34f 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -1,5 +1,7 @@ version: 2 +formats: all + build: os: ubuntu-22.04 tools: diff --git a/docs/commandline_interface.rst b/docs/commandline_interface.rst index 24f5785..61a767e 100644 --- a/docs/commandline_interface.rst +++ b/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. diff --git a/docs/conf.py b/docs/conf.py index bb53910..177153a 100644 --- a/docs/conf.py +++ b/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' diff --git a/docs/installation.rst b/docs/installation.rst index 2966f4e..cbe4e06 100644 --- a/docs/installation.rst +++ b/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 diff --git a/docs/requirements.txt b/docs/requirements.txt index b9ff4f6..ec5543b 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/docs/usage_examples.rst b/docs/usage_examples.rst index 3b41446..dc6e12b 100644 --- a/docs/usage_examples.rst +++ b/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] diff --git a/styleframe/style_frame.py b/styleframe/style_frame.py index 0a07f31..0b0dfe2 100644 --- a/styleframe/style_frame.py +++ b/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] diff --git a/styleframe/styler.py b/styleframe/styler.py index 00f919e..ce00c4a 100644 --- a/styleframe/styler.py +++ b/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)