# sphinx-excel <img src = "./documents/statics/logo.png" height = 120 align="right">
[![sphinx-excel](https://img.shields.io/badge/pypi-sphinx--excel-brightgreen)](https://pypi.org/project/sphinx-excel/)
[![Documentation Status](https://readthedocs.org/projects/sphinx-excel/badge/?version=latest)](https://sphinx-excel.readthedocs.io/en/latest/?badge=latest)
![pytest](https://github.com/zqmillet/sphinx-excel/actions/workflows/pytest.yml/badge.svg)
![mypy](https://github.com/zqmillet/sphinx-excel/actions/workflows/mypy.yml/badge.svg)
![flake8](https://github.com/zqmillet/sphinx-excel/actions/workflows/flake8.yml/badge.svg)
![pytest](https://github.com/zqmillet/sphinx-excel/actions/workflows/pytest.yml/badge.svg)
## introduction
sphinx-excel uses `openpyxl` to read an excel file and render it into sphinx document.
## installation
you can install sphinx-excel by `pip`.
``` bash
python3 -m pip install sphinx-excel
```
## setup
please add `sphinxcontrib.excel` into your `conf.py` file.
``` python
extensions = [
'sphinxcontrib.excel',
]
```
## usage
the following code will insert the first sheet of `tables.xlsx` into sphinx document.
``` rst
.. excel:: ./tables.xlsx
```
the `excel` directive will show the sheet name as the caption of table. you can use `:no-caption` to remove it.
``` rst
.. excel:: ./tables.xlsx
:no-caption:
```
if you want to specify the caption, you can use `:caption:` argument.
``` rst
.. excel:: ./tables.xlsx
:caption: hello world
```
`excel` directive supports all arguments of sphinx native `table` directive. for example, you can use `:align:` to change table align style.
``` rst
.. excel:: ./tables.xlsx
:align: center
```
if an excel file contains more than one sheets, you can use `:sheet:` arguments to specify which sheet to be rendered.
``` rst
.. excel:: ./tables.xlsx
:align: center
:sheet: stuff
```
the first line of table is in bold font, it means that the first line is header of table. if the table has two rows header, you can use `:headers:` to tell `excel` directive.
``` rst
.. excel:: ./tables.xlsx
:headers: 2
```
## one more thing
`excel` directive supports to render merged cell in excel. the content of the cell can be:
- math equtions,
- code snippets, and
- other directives.
Raw data
{
"_id": null,
"home_page": "https://github.com/zqmillet/sphinx-excel",
"name": "sphinx-excel",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "kinopico",
"author_email": "zqmillet@qq.com",
"download_url": "https://files.pythonhosted.org/packages/1c/8b/0a560a3d023081e9dff76ea25edd4ec170fd5b366d22641523a378a565d8/sphinx-excel-1.0.1.tar.gz",
"platform": null,
"description": "# sphinx-excel <img src = \"./documents/statics/logo.png\" height = 120 align=\"right\">\n\n[![sphinx-excel](https://img.shields.io/badge/pypi-sphinx--excel-brightgreen)](https://pypi.org/project/sphinx-excel/)\n[![Documentation Status](https://readthedocs.org/projects/sphinx-excel/badge/?version=latest)](https://sphinx-excel.readthedocs.io/en/latest/?badge=latest)\n![pytest](https://github.com/zqmillet/sphinx-excel/actions/workflows/pytest.yml/badge.svg)\n![mypy](https://github.com/zqmillet/sphinx-excel/actions/workflows/mypy.yml/badge.svg)\n![flake8](https://github.com/zqmillet/sphinx-excel/actions/workflows/flake8.yml/badge.svg)\n![pytest](https://github.com/zqmillet/sphinx-excel/actions/workflows/pytest.yml/badge.svg)\n\n## introduction\n\nsphinx-excel uses `openpyxl` to read an excel file and render it into sphinx document.\n\n## installation\n\nyou can install sphinx-excel by `pip`.\n\n``` bash\npython3 -m pip install sphinx-excel\n```\n\n## setup\n\nplease add `sphinxcontrib.excel` into your `conf.py` file.\n\n``` python\nextensions = [\n 'sphinxcontrib.excel',\n]\n```\n\n## usage\n\nthe following code will insert the first sheet of `tables.xlsx` into sphinx document.\n\n``` rst\n.. excel:: ./tables.xlsx\n```\n\nthe `excel` directive will show the sheet name as the caption of table. you can use `:no-caption` to remove it.\n\n``` rst\n.. excel:: ./tables.xlsx\n :no-caption:\n```\n\nif you want to specify the caption, you can use `:caption:` argument.\n\n``` rst\n.. excel:: ./tables.xlsx\n :caption: hello world\n```\n\n`excel` directive supports all arguments of sphinx native `table` directive. for example, you can use `:align:` to change table align style.\n\n``` rst\n.. excel:: ./tables.xlsx\n :align: center\n```\n\nif an excel file contains more than one sheets, you can use `:sheet:` arguments to specify which sheet to be rendered.\n\n``` rst\n.. excel:: ./tables.xlsx\n :align: center\n :sheet: stuff\n```\n\nthe first line of table is in bold font, it means that the first line is header of table. if the table has two rows header, you can use `:headers:` to tell `excel` directive.\n\n``` rst\n.. excel:: ./tables.xlsx\n :headers: 2\n```\n\n## one more thing\n\n`excel` directive supports to render merged cell in excel. the content of the cell can be:\n\n- math equtions,\n- code snippets, and\n- other directives.\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "an extension for sphinx to display excel table in sphinx documents",
"version": "1.0.1",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "ed2122908111ee04a9e764e5b3b7b2d8",
"sha256": "5e4865ec1fd54ff8ba3244e1912d2cc9868cdeb2cbe6d564297e13720fd5b931"
},
"downloads": -1,
"filename": "sphinx_excel-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ed2122908111ee04a9e764e5b3b7b2d8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 7630,
"upload_time": "2022-11-30T06:37:21",
"upload_time_iso_8601": "2022-11-30T06:37:21.940076Z",
"url": "https://files.pythonhosted.org/packages/1b/a8/d2df2303bb85e819a4108f5941cc8ad5b7c631e56664d95775ea2eec340a/sphinx_excel-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "4e732052f7bec4740a39b02674b6f3c5",
"sha256": "ef0bdb324399f17c0cf55704621ff7f7b976c1bac648d9820de9a28b605d5e59"
},
"downloads": -1,
"filename": "sphinx-excel-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "4e732052f7bec4740a39b02674b6f3c5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5669,
"upload_time": "2022-11-30T06:37:24",
"upload_time_iso_8601": "2022-11-30T06:37:24.085253Z",
"url": "https://files.pythonhosted.org/packages/1c/8b/0a560a3d023081e9dff76ea25edd4ec170fd5b366d22641523a378a565d8/sphinx-excel-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-11-30 06:37:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "zqmillet",
"github_project": "sphinx-excel",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinx-excel"
}