Thanks to visit codestin.com
Credit goes to github.com

Skip to content

MRG: Update docs #279

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.

Sign up for GitHub

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

Jump to bottom
Merged
merged 8 commits into from
Aug 3, 2017
Merged

MRG: Update docs #279

merged 8 commits into from
Aug 3, 2017

Conversation

larsoner
Copy link
Contributor

@larsoner larsoner commented Jul 31, 2017 •
edited
Loading

Closes #276.
Closes #277.

WIP because building freezes on my machine at Embedding documentation hyperlinks in examples ... (40%) so I want to see what CircleCI gives, and I still want/need to address #277.

@larsoner larsoner changed the title WIP: Update docs MRG: Update docs Jul 31, 2017
@larsoner
Copy link
Contributor Author

Old docs:

http://sphinx-gallery.readthedocs.io/en/latest/advanced_configuration.html

This PR's version:

https://154-25860190-gh.circle-artifacts.com/0/home/ubuntu/sphinx-gallery/rtd_html/advanced_configuration.html

Ready for review/merge from my end.

Titan-C
Titan-C reviewed Jul 31, 2017
View reviewed changes
Copy link
Member

@Titan-C Titan-C left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This new order and table of context looks appropriate to me. I don't understand why code-blocks language specification got changed. I myself was never explicit on bash as there is not much syntax highlighting to be made there. I would argue making python and bash blocks explicit.

README.rst
``doc/conf.py`` file with:

.. code-block:: python
``doc/conf.py`` file with::
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm just curious. Why do you make bash code blocks now explicit, make the python blocks now un-explicit?

@larsoner
Copy link
Contributor Author

larsoner commented Jul 31, 2017 via email

choldgraf
choldgraf reviewed Aug 1, 2017
View reviewed changes
doc/advanced_configuration.rst
=============
Configuration
=============

Copy link
Contributor

@choldgraf choldgraf Aug 1, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd start with a short description of what is to come. Something like

"Configuration and customization of sphinx-gallery is done with a dictionary specified in your conf.py file. A list of the possible keys are shown below, and are explained in greater detail elsewhere in the documentation."

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(edited this slightly, just in case you're reading from your email ;-) )

choldgraf
choldgraf reviewed Aug 1, 2017
View reviewed changes
doc/advanced_configuration.rst

And some things can be tweaked directly in CSS:

- ``.sphx-glr-thumbcontainer`` (:ref:`setting_thumbnail_size`)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

did we ever add the more descriptive classes for other objects (e.g. DIVs etc)?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

all our CSS is in sphinx_gallery/_static/gallery.css, and every user can always overload that with their own CSS. I left PR #210 forgotten, at some point we shall go back to it.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah yeah - I meant using more sphinx-gallery-specific classes in the DIVs...I'll comment over in #210!

@choldgraf
Copy link
Contributor

This looks almost ready to go for me - two quick comments but then I am +1 on merge

@larsoner
Copy link
Contributor Author

larsoner commented Aug 1, 2017

@choldgraf can you see if you're happy with the latest header change?

The only remaining question in my mind is is this list of options complete? I saw at least find_mayavi_figures not documented, so I added that one.

I also saw over in #210 something about multi-img and it made me think there was some config var that allows using multiple thumbnail images (?) but I don't see it documented anywhere. From looking through the code with gallery_conf I don't see any other entries missing, so I guess not.

@larsoner
Copy link
Contributor Author

larsoner commented Aug 1, 2017

Latest build:

https://157-25860190-gh.circle-artifacts.com/0/home/ubuntu/sphinx-gallery/rtd_html/advanced_configuration.html

@choldgraf
Copy link
Contributor

I think we should merge this, and open an issue about the more general challenge of "how do we ensure that all the functionality of SG (within the conf.py file) is tested and documented"...I think the repo's conf.py file should have an example of each possible config option, but I could see folks disagreeing

@choldgraf
Copy link
Contributor

I'll merge this tomorrow AM if nobody protests :-)

@larsoner
Copy link
Contributor Author

larsoner commented Aug 1, 2017

Okay I've also added these to the conf.py:

# See warnings about bad links
nitpicky = True
# we intentionally link outside images
suppress_warnings = ['image.nonlocal_uri']

... because without the first, I didn't know that the links I added to :mod:matplotlib and :mod:mayavi were no good (and needed to be :mod:matplotlib.pyplot and :mod:mayavi.mlab), and without the second, we get extra warnings that we don't need to see.

This should at least make visible other similar errors in the future.

@larsoner larsoner mentioned this pull request Aug 2, 2017
Merged
@choldgraf
Copy link
Contributor

I'm not sure what the nitpicky change means...is that just a sphinx param to throw an error if it finds a warning?

@larsoner
Copy link
Contributor Author

larsoner commented Aug 3, 2017 via email

@larsoner larsoner mentioned this pull request Aug 3, 2017
Merged
@larsoner
Copy link
Contributor Author

larsoner commented Aug 3, 2017

Ping @choldgraf this should be good to go

@choldgraf choldgraf merged commit e9b1a25 into sphinx-gallery:master Aug 3, 2017
@choldgraf
Copy link
Contributor

🎉🎉 🎉 🎉

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@Titan-C Titan-C Titan-C left review comments

@choldgraf choldgraf choldgraf left review comments

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@larsoner @choldgraf @Titan-C