Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document bokeh.sampledata #9329

Closed
bryevdv opened this issue Oct 27, 2019 · 3 comments · Fixed by #11130
Closed

Document bokeh.sampledata #9329

bryevdv opened this issue Oct 27, 2019 · 3 comments · Fixed by #11130

Comments

@bryevdv
Copy link
Member

@bryevdv bryevdv commented Oct 27, 2019

The Reference Guide page is nearly empty. The bokeh.sampledata module should automatically include relevant submodules in its main docsring, and all the submodule docstrings should be updated/completed to be useful, e.g. explain what the module contains, or show example data, or link/include examples that use the data.

@bryevdv
Copy link
Member Author

@bryevdv bryevdv commented Nov 4, 2019

The simplest/quickest solution:

  • Add docstrings with a common/similar format to all the sample data modules.
  • manually add automodule sphinx directives to the top level module docstring

If we wanted to go for a little more automated approach, then the second step could be:

  • create a :bokeh-sampledata: directive that scans the bokeh/sampledata directory for all relevant submodules and adds automodule directives atomatically for them.

@Tekaichi
Copy link
Contributor

@Tekaichi Tekaichi commented Mar 15, 2020

The simplest/quickest solution would be adding something like the following for each .py in the sampledata folder ?
Should I also add the files inside _data?

bokeh.sampledata.airports
.. automodule:: bokeh.sampledata.airports
   :members:

Right now, I'm just going for the first solution but would like to explore the second one later.

@bryevdv
Copy link
Member Author

@bryevdv bryevdv commented Mar 15, 2020

@Tekaichi All of the files in _data are accessed via one of the Python modules in bokeh.sampledata, so I think it suffices to just add the docstrings to the modules. Just to be clear up front: the bulk of the work here is adding all the docstrings. Ideally each data docstring should describe the format of the data variables in the module, provide provenance information (where known), have some sample snippets showing how to work with the data, and if possible link to relevant examples.

@bryevdv bryevdv mentioned this issue Apr 5, 2021
2 tasks
@bryevdv bryevdv removed this from the short-term milestone Apr 5, 2021
@bryevdv bryevdv added this to the 2.4 milestone Apr 5, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

2 participants