NotificationsYou must be signed in to change notification settings
Fork7.9k
Star21.4k

Cleanup doc/conf.py & local sphinx extensions#9708

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 ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Jump to bottom

Merged

timhoffm merged 2 commits intomatplotlib:masterfromanntzer:confpy

Feb 6, 2018

Merged

Cleanup doc/conf.py & local sphinx extensions#9708

timhoffm merged 2 commits intomatplotlib:masterfromanntzer:confpy

Feb 6, 2018

Conversation

Copy link

Contributor

anntzer commentedNov 6, 2017•
edited
Loading

Split out extensions to their own files.

Emit the latex symbol tables without breaks.

PR Summary

PR Checklist

Has Pytest style unit tests
Code is PEP 8 compliant
New features are documented, with examples if plot related
Documentation is sphinx and numpydoc compliant
Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)
Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way

anntzer added the Documentation label

Nov 6, 2017

anntzer force-pushed theconfpy branch 4 times, most recently from08d3351 tocf0106dCompare

November 6, 2017 23:27

tacaswell reviewed

Nov 7, 2017

View reviewed changes

doc/sphinxext/gen_rst.py Outdated

		@@ -1,173 +0,0 @@
		"""

Copy link

Member

Choose a reason for hiding this comment

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

I am concerned that someone is depending on this. There is not much harm in carrying this file.

Copy link

Member

Choose a reason for hiding this comment

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

On second thought, was this even importable outside of our docs build? 🐑

Copy link

Member

Choose a reason for hiding this comment

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

The importable stuff is inlib/matplotlib/sphinxext.

Copy link

Member

tacaswell commentedNov 7, 2017

👍 conditional ongen_rst not being importable by anyone else.

tacaswell added this to thev2.2 milestone

Nov 7, 2017

Copy link

ContributorAuthor

Choose a reason for hiding this comment

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

If we drop support for sphinx older than 1.3 we can probably replace this with the build in autodoc_mock_imports inhttp://www.sphinx-doc.org/en/stable/ext/autodoc.html#confval-autodoc_mock_imports If we drop versions below 1.6 we can make it simpler by only mocking the top level modules. As I recall it I added the mocking here predates Sphinx 1.3 which is why its done manually

Copy link

Member

tacaswellNov 7, 2017

Choose a reason for hiding this comment

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

What is the argument for not requiring 1.6?

Copy link

Member

jenshnielsenNov 7, 2017

Choose a reason for hiding this comment

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

The only one I can think of is building with Sphinx from apt-get/yum but I am not sure we need to support that

Copy link

Member

tacaswellNov 7, 2017

Choose a reason for hiding this comment

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

I think debian does build our docs as part of the build process.@sandrotosi How much pain would it cause you to bump to sphinx 1.6?

Copy link

Contributor

sandrotosiNov 7, 2017

Choose a reason for hiding this comment

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

it would be no problem at all, actually it would be really helpful as in Debian we're migrating to sphinx 1.6 and the current doc cannot be built with that version, so thanks for pushing to use 1.6 :)

Copy link

Contributor

sandrotosiNov 7, 2017

Choose a reason for hiding this comment

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

nope, what i really should do is updating matplotlib in debian (which i'll do as soon as i find time for it)

Copy link

ContributorAuthor

anntzerNov 7, 2017

Choose a reason for hiding this comment

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

I don't think that's going to work because we need some mocked objects to betypes (so that we can subclass them) orcallables with specific return values (sip.getapi), rather than just "existing" (in other words, because we are running code at the toplevel rather than just defining a bunch of functions).

Copy link

Member

KojoleyNov 11, 2017

Choose a reason for hiding this comment

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

Debian 7 “Wheezy” is still supported (https://wiki.debian.org/LTS) and it has1.1.3 sphinx (https://packages.debian.org/search?keywords=python-sphinx) =\

Copy link

Contributor

sandrotosiNov 11, 2017

Choose a reason for hiding this comment

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

TBH i wouldnt worry about wheezy (nor jessie) - if anyone will want to get an updated mpl on that release, they'll have to take care of backporting a tons of other deps (numpy in primis) before caring about sphinx and missing documentation

Copy link

Member

KojoleyNov 11, 2017

Choose a reason for hiding this comment

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

True, but even stretch does not have 1.6

Copy link

ContributorAuthor

anntzer commentedNov 7, 2017

I think the mocking would be better resolved in a separate PR that strips out all thebackend_foo individual doc pages (which are incomplete anyways) in favor of a single, hand-written doc for all the backends that lists the common public API of all backends.

anntzer force-pushed theconfpy branch fromcf0106d to36043ffCompare

November 7, 2017 19:23

anntzer mentioned this pull request

Nov 17, 2017

Backend switching#9795

Closed

anntzer mentioned this pull request

Dec 31, 2017

Remove gen rst#10137

Merged

anntzer force-pushed theconfpy branch from36043ff toa5ba245Compare

December 31, 2017 23:53

Copy link

ContributorAuthor

anntzer commentedJan 1, 2018

Also got rid of the mpl_examples symlink, which is now unneeded.

Copy link

Member

QuLogic commentedJan 9, 2018

A tangentially related request; can you move thesphinx_gallery import to aftercheck_deps so sphinx doesn't fail with an import error instead of our proper error message?

anntzer force-pushed theconfpy branch froma5a0adc to84be143Compare

January 9, 2018 03:13

Copy link

ContributorAuthor

anntzer commentedJan 9, 2018

done

anntzer mentioned this pull request

Jan 11, 2018

Additional docstring recommendations#10225

Closed

Copy link

Member

jklymak commentedJan 19, 2018

This needs a rebase and tests to pass....

anntzer force-pushed theconfpy branch 2 times, most recently fromae39a7a to9597c9aCompare

January 20, 2018 09:31

Copy link

ContributorAuthor

anntzer commentedJan 20, 2018

done (well, OSX is backlogged...)

timhoffm reviewed

Feb 3, 2018

View reviewed changes

doc/conf.py Outdated

		# Use IPython's console highlighting by default
		extensions.extend(['IPython.sphinxext.ipython_console_highlighting',
		'IPython.sphinxext.ipython_directive'])
		from sphinx_gallery.sorting import ExplicitOrder

Copy link

Member

timhoffmFeb 3, 2018

Choose a reason for hiding this comment

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

Why move the import from the head of the file here?

Copy link

Member

QuLogicFeb 3, 2018

Choose a reason for hiding this comment

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

#9708 (comment)

Copy link

Member

timhoffmFeb 3, 2018

Choose a reason for hiding this comment

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

Thanks. IMO this could use a short comment.

Copy link

ContributorAuthor

anntzerFeb 6, 2018

Choose a reason for hiding this comment

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

done

doc/devel/documenting_mpl.rst Outdated

		This is rendered as :doc:`/tutorials/introductory/customizing` (see the
		bottom of the page. Note that this is in a tutorial; See
		:ref:`writing-examples-and-tutorials` below)
		This is rendered as at the bottom of

Copy link

Member

timhoffmFeb 3, 2018

Choose a reason for hiding this comment

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

doc/devel/documenting_mpl.rst Outdated

		referencewhen the documentation is built.
		Note that the python script that generates the plot is referred to, rather than
		any plot that is created; sphinx-gallerywill provide thecorrect reference
		when the documentation is built.

Copy link

Member

timhoffmFeb 3, 2018

Choose a reason for hiding this comment

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

I would leave the . instead of the ;

Copy link

Member

QuLogic commentedFeb 4, 2018

Needs a rebase now, too.

anntzer force-pushed theconfpy branch 2 times, most recently from55ce5fd to8f4fd73Compare

February 6, 2018 08:16

Copy link

ContributorAuthor

anntzer commentedFeb 6, 2018

done

anntzer added2 commits

February 6, 2018 09:28

Cleanup doc/conf.py.

de81397

Emit the latex symbol tables without breaks.

Get rid of the mpl_examples symlink.

734a189

anntzer force-pushed theconfpy branch from8f4fd73 to734a189Compare

February 6, 2018 08:28

timhoffm merged commitb7d87d9 intomatplotlib:master

Feb 6, 2018

anntzer deleted the confpy branch

February 6, 2018 18:26

QuLogic modified the milestones:needs sorting,v2.2.0

Feb 12, 2018

tacaswell mentioned this pull request

Apr 30, 2018

Remove mpl_examples symlink.#11141

Merged

6 tasks

Labels

Documentation

8 participants

		'matplotlib.sphinxext.plot_directive',
		'sphinxext.github',
		'sphinxext.math_symbol_table',
		'sphinxext.mock_gui_toolkits',

Movatterモバイル変換

Uh oh!

Cleanup doc/conf.py & local sphinx extensions#9708

Cleanup doc/conf.py & local sphinx extensions#9708

Uh oh!

Conversation

anntzer commentedNov 6, 2017• editedLoading Uh oh!There was an error while loading.Please reload this page.

Uh oh!

PR Summary

PR Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tacaswell commentedNov 7, 2017

Uh oh!

anntzer commentedNov 7, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anntzer commentedNov 7, 2017

Uh oh!

anntzer commentedJan 1, 2018

Uh oh!

QuLogic commentedJan 9, 2018

Uh oh!

anntzer commentedJan 9, 2018

Uh oh!

jklymak commentedJan 19, 2018

Uh oh!

anntzer commentedJan 20, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

QuLogic commentedFeb 4, 2018

Uh oh!

anntzer commentedFeb 6, 2018

Uh oh!

Uh oh!

anntzer commentedNov 6, 2017•
edited
Loading