Interactive charts in sphinx HTML docs, using plot.ly and D3
MIT License
Interactive charts, graphs and figures for sphinx using plotly v2.8.3 and D3.
See the documentation above for more, but in an nutshell, add the extension to your conf.py
:
extensions = [
...
'sphinx_charts.charts'
]
Paste the following into a new file <your_docs_src_directory>/charts/test.json
:
{
"data": [
{
"x": [1, 2, 3, 4, 5],
"y": [1, 2, 4, 8, 16]
}
],
"layout": {
"margin": {"t": 15, "b": 30, "r": 15, "l": 35}
}
}
Include the following directive in your *.rst
file:
.. chart:: charts/test.json
This is the caption of the chart
... and away you go!
Note: You don't need to pay attention to the following unless you plan to develop sphinx_charts itself.
{{
in your new repository. Do search and replace for the various terms - it's obvious what they are, like replace {{github_username}}
with your github username!LICENSE
.You need to install pre-commit to get the hooks working. Do:
pip install pre-commit
pre-commit install
Once that's done, each time you make a commit, the following checks are made:
Upon failure, the commit will halt. Re-running the commit will automatically fix most issues except:
You can run pre-commit hooks without making a commit, too, like:
pre-commit run black --all-files
or
# -v gives verbose output, useful for figuring out why docs won't build
pre-commit run build-docs -v
Please raise an issue on the board (or add your $0.02 to an existing issue) so the maintainers know what's happening and can advise / steer you.
Create a fork of {{library_name}}, undertake your changes on a new branch, (see .pre-commit-config.yaml
for branch naming conventions). To run tests and make commits,
you'll need to do something like:
git clone <your_forked_repo_address> # fetches the repo to your local machine
cd sphinx_charts # move into the repo directory
pyenv virtualenv 3.6.9 myenv # Makes a virtual environment for you to install the dev tools into. Use any python >= 3.6
pyend activate myenv # Activates the virtual environment so you don't screw up other installations
pip install -r requirements-dev.txt # Installs the testing and code formatting utilities
pre-commit install # Installs the pre-commit code formatting hooks in the git repo
tox # Runs the tests with coverage. NB you can also just set up pycharm or vscode to run these.
Adopt a Test Driven Development approach to implementing new features or fixing bugs.
Ask the sphinx_charts
maintainers where to make your pull request. We'll create a version branch, according to the
roadmap, into which you can make your PR. We'll help review the changes and improve the PR.
Once checks have passed, test coverage of the new code is >=95%, documentation is updated and the Review is passed, we'll merge into the version branch.
Once all the roadmapped features for that version are done, we'll release.
The process for creating a new release is as follows:
vX.Y.Z
master
branch.vX.Y.Z
setup.py
is correct and matches the branch version.The documentation will build automatically in a pre-configured environment when you make a commit.
In fact, the way pre-commit works, you won't be allowed to make the commit unless the documentation builds, this way we avoid getting broken documentation pushed to the main repository on any commit sha, so we can rely on builds working.
If you did need to build the documentation
Install doxgen
. On a mac, that's brew install doxygen
; other systems may differ.
Install sphinx and other requirements for building the docs:
pip install -r docs/requirements.txt
Run the build process:
sphinx-build -b html docs/source docs/build