README to show how to edit the documentation #1122
Conversation
Unsolicited lessons learned from updating the altair documentation.
doc/README.md
Outdated
| dummy to check syntax errors of document sources | ||
|
|
||
| ``` | ||
| For most updates, run `make html` and the documentation will generate in a sub folder `_build`. You can open `_build/html/index.html` to view the documenation as local static files which should give you a good preview of how any updates will look. |
There was a problem hiding this comment.
I'd recommend the following to see the full site:
$ cd _build/html
$ python -m http.server # python 3 requiredAnd then open http://0.0.0.0:8888 to see the served pages.
Sometimes just opening directly from the file system does not properly load vega-lite charts.
doc/README.md
Outdated
|
|
||
| When updating the user guide the following conventions are helpful: | ||
|
|
||
| * When referring to an Altair class or function preface it with ``:class:`` or ``:func`` and the rendering engine will automatically link it to the appropriate section in the API reference. |
There was a problem hiding this comment.
Maybe also note that the .. currentmodule: altair directive needs to be used somewhere in the file if you don't want to type the full function name.
| ``` | ||
| pip install selenium | ||
| ``` | ||
|
|
There was a problem hiding this comment.
I tried doing a fresh install and I had to run
pip install recommonmark
as well to make things work. Should recommonmark be added to doc/requirements.txt? @jakevdp
There was a problem hiding this comment.
I think recommonmark is part of requirements_dev.txt. We should probably either add pip install requirements_dev.txt to the list of steps to follow, or add the sphinx-related requirements to doc/requirements.txt
1. Added command to serve the static using standard library http server 2. Reference README for general development guidelines.
1. Import module at top of files 2. recommonmark as requirements
|
@eitanlees thanks for your review. I just pushed some changes based on your feedback. Specifically in the first paragraph, I referred people to the main My thoughts are a discussion of setting up a virtual env and branch checkouts is ideally handled there. The most important thing to know when changing the docs is that you need to set-up all the dependencies for Altair, locally install Altair, AND set-up dependencies for the docs and I think this version currently gets that across. Another reason I am glossing over it slightly is that I don't use Anaconda nor Windows a discussion of the virtual environments really needs some notes about both those cases. @jakevdp added server command and model import also added recommonMark to requirements though I am not sure where its actually used so maybe want to keep it out. |
|
I think pointing to the main As far as |
|
Thanks @kindofluke and @eitanlees - sorry for the delayed review, I was traveling last week. As I mentioned above, the |
| For most updates, run `make html` and the documentation will generate in a sub folder `_build`. You can open `_build/html/index.html` to view the documenation as local static files which should give you a good preview of how any updates will look. Even better, use the command below to serve the static files and you will be able to navigate the whole documentation website. | ||
|
|
||
| ``` | ||
| cd doc/_buld/_html |
|
@binste, I saw your comment regarding improving the README (#2599 (reply in thread)). Is this draft PR of interested for you? |
|
Thanks @mattijn, it is indeed! You can close this PR and I will add the content from @kindofluke (with them as author) to the |
* Clarify in Getting Help that GH issues are for bugs and feature requests, not questions * Remove section 'A Python API for statistical visualizations' as outdated regarding frontends and fully contained in documentation * Remove mentions of traitlets package as no longer used. Update development sections and refer to documentation as readme gets stale quickly * Deduplicate mentioning of tutorial notebooks. Some smaller improvements * Deduplicate mentioning of tutorial notebooks. Some smaller improvements * How to contribute to the documentation taken over from #1122 * Switch to recommending vl-convert-python for thumbnails. Minor language improvements * Clarify that vl-convert-python is easier to build docs but altair_saver is required for deployment as one thumbnail cannot be generated otherwise * Mention google group * Apply suggestions from code review Co-authored-by: Mattijn van Hoek <[email protected]> * Update RELEASING.md Co-authored-by: Mattijn van Hoek <[email protected]> * Further clarify when to uninstall vl-convert-python * Install vl-convert-python by default for documentation and clarify when it needs to be uninstalled in favor of altair_saver * Apply suggestions from code review Co-authored-by: Mattijn van Hoek <[email protected]> * Update RELEASING.md Co-authored-by: Mattijn van Hoek <[email protected]> * Update black command to show diff * Apply suggestions from code review Co-authored-by: Joel Ostblom <[email protected]> * Remove mention of google group * Mention stackoverflow answer re Plotly vs. Altair Co-authored-by: Luke Shulman <[email protected]> Co-authored-by: Mattijn van Hoek <[email protected]> Co-authored-by: Joel Ostblom <[email protected]>
Unsolicited lessons learned from updating the altair documentation.