Sphinx docs #39

goodboy · 2017-01-31T06:48:24Z

@hpk42 @RonnyPfannschmidt @nicoddemus so after much delay (and many iterations) I finally got around to finishing this. It's only an initial draft but I tried to cover as much as possible in an effort to address #14.

I think it's worth discussing some of the "internal" objects (those types prefixed by _) which should really just be public (although maybe not exposed for import via __all__).

Also note the current docs build is failing.

Let me know what you guys think as I'm happy to change anything you think could be better.

Thanks!

nicoddemus

First let me thank you @tgoodlet for the excellent work! The documentation so far looks great and is an excellent start.

I left some small comments and suggestions, but please note that I'm not an English speaker so I might be off track on some of them.

nicoddemus · 2017-01-31T20:55:41Z

docs/calling.rst

+------------------
+By default calling a hook results in all underlying :ref:`hookimpls
+<impls>` functions to be invoked in sequence via a loop. Any function
+which returns a none ``None`` result will have that result appended to


"none None" reads a little weird to me. Perhaps "returns a value different than None will have..."?

Noted I'll add it.

nicoddemus · 2017-01-31T20:59:19Z

docs/calling.rst

+a :py:class:`list` which is returned by the call.
+
+The only exception to this behaviour is if the hook has been marked to return
+its :ref:`firstresult` in which case only the first single none ``None`` value


Ditto about "none None" here.

nicoddemus · 2017-01-31T21:01:31Z

docs/calling.rst

+
+Historic calls
+--------------
+You can invoke certain hooks with all call *history* provided to each *hookimpl*


This sentence reads strange to me: "certain hooks with all call history provided to each hookimpl", IMO I think just removing this phrase and starting with "A historic call allows for all newly..." from the next paragraph.

Sounds good :)

nicoddemus · 2017-01-31T21:02:50Z

docs/index.rst

-Contents:
+In fact, ``pytest`` is itself composed as a set of ``pluggy`` plugins
+which are invoked in sequence according to a well defined set of protocols.
+Some 150+ plugins use ``pluggy`` to extend and customize ``pytest``'s default behaviour.


Just realized some of these days that this number is over 273 now: http://plugincompat.herokuapp.com/

😁

Ok 200+ it is!
I'll link to that page as well?

nicoddemus · 2017-01-31T21:03:30Z

docs/index.rst


+In essence, ``pluggy`` enables function `hooking`_ so you can build "pluggable" systems.


We might want to add a note that tox has been using pluggy as well to emphasize that pluggy is a general system.

I was thinking about a section on Projects which use pluggy but I didn't know the full list offhand.

@nicoddemus is there any more besides tox and pytest plugins? execnet maybe?

nicoddemus · 2017-01-31T23:17:57Z

docs/index.rst

+subscriptions and can be thought of and used as a rudimentary busless `publish-subscribe`_
+event system.
+
+``pluggy``'s approach is meant to let a designer think carefuly about which objects are


nicoddemus · 2017-01-31T23:19:46Z

docs/index.rst

+Development
+-----------
+Great care must taken when hacking on ``pluggy`` since many mature
+projects rely on it. Until there is a more automated CI process in


I think this part about "automated CI process" can be removed since we have AppVeyor and Travis automated testing.

Ahh good point. Yeah I kind of forgot that there was already CI hehe.

nicoddemus · 2017-01-31T23:24:36Z

docs/index.rst

@@ -1,23 +1,108 @@
-.. pluggy documentation master file, created by


IMHO our index should only contain an index that points to other documentation... it helps to structure the documentation better. I suggest an index which looks (loosely) like:

Introduction

Specs/implementations

First example

Managing

Plugin Registry

Would be nice.

What do others think?

@nicoddemus sure if you'd like?

Do you mean more like pytest's index.rst and docs homepage which seems to double as the github readme?

So you want me to strip the User Guide section (with its TOC) and have a docs section which links to individual .rst documents?

nicoddemus · 2017-01-31T23:26:37Z

docs/define.rst

+*options* passed as keyword arguments.
+
+
+.. note::


nicoddemus · 2017-01-31T23:33:25Z

docs/manage.rst

+- :py:meth:`~pluggy.PluginManager.get_canonical_name()`- get a *plugin*'s
+  canonical name (the name it was registered with)
+- :py:meth:`~pluggy.PluginManager.get_plugin()` - retrieve a plugin by its
+  canonical name using


This sentence seems incomplete

goodboy · 2017-02-01T02:34:55Z

@nicoddemus fixed everything except for

the index.rst discussion
the missing list of major dependent projects

OH and I'll swash all those changes ^ into a single commit before we merge yeah?

nicoddemus · 2017-02-01T10:31:20Z

the index.rst discussion

Yes let's wait for the opinions of others first.

into a single commit before we merge yeah?

Sounds good.

nicoddemus · 2017-02-01T10:33:03Z

docs/define.rst

+First result only
+^^^^^^^^^^^^^^^^^
+A *hookspec* can be marked such that when the *hook* is called the call loop
+will only invoke up to the first *hookimpl* which returns a none ``None`` result.


Oops found another "none none" occurrence, for consistency we probably need to rephrase this as well.

nicoddemus · 2017-02-01T10:33:17Z

Thanks @tgoodlet for the quick edits! 👍

hpk42 · 2017-02-01T15:46:42Z

thanks @tgoodlet -- very good work and looking forward to see this online!
I'd prefer if we had fewer docs, though. I find editing and keeping a few documents consistent easier than many. We could then use automatic toc/content generation at the top of a single doc.

That being said, i am also fine to merge as is if you don't agree or don't want to go for it right now. Please be prepared then that i might do a PR sometime which reduces the number of docs, though :)

goodboy · 2017-02-01T16:07:37Z

I find editing and keeping a few documents consistent easier than many. We could then use automatic toc/content generation at the top of a single doc.

So would you like the individual .rst files merged into one or two then @hpk42?

I guess I was just trying to follow the normal doc layout I've seen in other projects; pytest has its docs organized this way with multiple documents as well. I'm not sure what you mean by the automatic toc/content generation? If you can point me to how to use that in the sphinx docs I'll definitely take a look :)

Please be prepared then that i might do a PR sometime which reduces the number of docs, though :)

Heh of course that's always welcome :D

hpk42 · 2017-02-02T09:17:51Z

On Wed, Feb 01, 2017 at 08:07 -0800, goodboy wrote: > I find editing and keeping a few documents consistent easier than many. We could then use automatic toc/content generation at the top of a single doc. So would you like the individual .rst files merged into one or two then @hpk42? I guess I was just trying to follow the normal doc layout I've seen in other projects; `pytest` has its docs [organized this way](https://raw.githubusercontent.com/pytest-dev/pytest/master/doc/en/contents.rst) with multiple documents as well. I'm not sure what you mean by the *automatic toc/content generation*? If you can point me to how to use that in the sphinx docs I'll definitely take a look :)

The in-page TOC generation happens with this directive: .. contents:: And yes, pytest docs have multiple files but key ones like "fixture.rst" are >1000 LOC. Concretely, if calling.rst, define.rst and manage.rst all went into the index.rst file with the above directive it's be a nice page where you can follow links to and between sections without server reload. That'd be a roughly 700LOC file which is fine i think. One can still give out/have URLs which point to specific sections through "#". I also kind of like this single-file doc (even api_reference could be added at the very end) because pluggy is supposed to be a compact/little thing, not a huge framework :)

goodboy · 2017-02-03T23:57:42Z

@hpk42 sounds good I'll make the change this weekend :)

goodboy · 2017-02-03T23:58:55Z

Oh and just to remind myself I need to fix up the README.rst; it's still got come markdown links in it.

goodboy · 2017-02-04T23:55:20Z

@hpk42 ok so after looking at what .. contents:: does I don't think it's necessary given that the sphinx theme we're using (which is also now the default by the way) already builds a TOC on the left hand side (you should try building from my branch locally).

So I've just merged everything into one big index.rst.
Let me know what you think.

PS still tweaking the logo...

goodboy · 2017-02-05T18:57:25Z

@hpk42 @RonnyPfannschmidt @nicoddemus ok so I've addressed mostly everything and have squashed the history.

Please let me know if I'm missing anything otherwise I think this is pretty much ready to land :)

nicoddemus

LGTM!

goodboy · 2017-02-05T22:30:56Z

@nicoddemus shoot just realized I rebased this onto my master which has another PRs worth of changes on it..

Fixing that now.

Covers everything in the original pluggy.py module's doc string in much more detail with links to external resources as seemed fit. Resolves pytest-dev#14

We now have full sphinx docs as per pytest-dev#14. pluggy.py is the entire project and it doesn't make much sense to describe that module's contents other then saying "this is it folks".

Resolves pytest-dev#40

nicoddemus · 2017-02-06T11:37:01Z

Great, thanks! I will let @hpk42 merge this one. 😁

goodboy · 2017-02-08T03:26:54Z

@hpk42 any news?

I was hoping to get at least this one before I start bugging you and @RonnyPfannschmidt about my other PRs ;)

hpk42 · 2017-02-08T08:26:30Z

thanks for the continued work. fwiw was ill for 10 days, getting better now.

goodboy · 2017-02-08T08:28:06Z

@hpk42 no worries!
I was sick all last week as well. I guess us northerners have something going around ;)

nicoddemus reviewed Jan 31, 2017

View reviewed changes

nicoddemus reviewed Feb 1, 2017

View reviewed changes

goodboy force-pushed the sphinxdocs branch from e389b4f to 4404d1b Compare February 4, 2017 23:51

goodboy force-pushed the sphinxdocs branch 2 times, most recently from a8432e4 to 1b40531 Compare February 5, 2017 18:42

nicoddemus approved these changes Feb 5, 2017

View reviewed changes

Tyler Goodlet added 5 commits February 5, 2017 17:33

Initial docs draft

e98b20c

Covers everything in the original pluggy.py module's doc string in much more detail with links to external resources as seemed fit. Resolves pytest-dev#14

Merge all documents into index.rst

4d7decb

Drop the monolithic doc string

9476b02

We now have full sphinx docs as per pytest-dev#14. pluggy.py is the entire project and it doesn't make much sense to describe that module's contents other then saying "this is it folks".

Add a plug logo

04d7b29

Resolves pytest-dev#40

Fix up README

dfcbf3f

goodboy force-pushed the sphinxdocs branch from ed8fc42 to dfcbf3f Compare February 5, 2017 22:36

hpk42 merged commit 21771da into pytest-dev:master Feb 8, 2017

This was referenced Sep 6, 2017

Update pluggy to 0.5.2 amureki/whoisp#47

Closed

Update pluggy to 0.5.2 DavidHickman/calendary#134

Closed

pyup-bot mentioned this pull request Sep 18, 2017

Scheduled weekly dependency update for week 38 qutebrowser/qutebrowser#2985

Closed

pyup-bot mentioned this pull request Sep 25, 2017

Scheduled weekly dependency update for week 39 qutebrowser/qutebrowser#3031

Merged

pyup-bot mentioned this pull request Oct 5, 2017

Initial Update aio-libs/async-lru#11

Closed

pyup-bot mentioned this pull request Oct 29, 2017

Update pluggy to 0.5.2 uppsaladatavetare/foobar-api#56

Closed

This was referenced Nov 24, 2017

Update pluggy to 0.6.0 amureki/whoisp#76

Closed

Update pluggy to 0.6.0 DavidHickman/calendary#181

Open

Update pluggy to 0.6.0 StuartJSquires/markov_slackbot#147

Closed

pyup-bot mentioned this pull request Jan 19, 2018

Update pluggy to 0.6.0 Poorvak/http_pipeline#8

Merged

pyup-bot mentioned this pull request Feb 8, 2018

Initial Update aio-libs/aiocassandra#9

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Sphinx docs #39

Sphinx docs #39

goodboy commented Jan 31, 2017 •

edited

Loading

nicoddemus left a comment

nicoddemus Jan 31, 2017

goodboy Feb 1, 2017

nicoddemus Jan 31, 2017

nicoddemus Jan 31, 2017

goodboy Feb 1, 2017

nicoddemus Jan 31, 2017

goodboy Feb 1, 2017 •

edited

Loading

nicoddemus Jan 31, 2017

goodboy Feb 1, 2017

nicoddemus Jan 31, 2017

nicoddemus Jan 31, 2017

goodboy Feb 1, 2017

nicoddemus Jan 31, 2017

goodboy Feb 1, 2017

nicoddemus Jan 31, 2017

nicoddemus Jan 31, 2017

goodboy commented Feb 1, 2017 •

edited

Loading

nicoddemus commented Feb 1, 2017

nicoddemus Feb 1, 2017

nicoddemus commented Feb 1, 2017

hpk42 commented Feb 1, 2017

goodboy commented Feb 1, 2017

hpk42 commented Feb 2, 2017 via email

goodboy commented Feb 3, 2017

goodboy commented Feb 3, 2017

goodboy commented Feb 4, 2017

goodboy commented Feb 5, 2017

nicoddemus left a comment

goodboy commented Feb 5, 2017

nicoddemus commented Feb 6, 2017

goodboy commented Feb 8, 2017

hpk42 commented Feb 8, 2017

goodboy commented Feb 8, 2017


		In essence, ``pluggy`` enables function `hooking`_ so you can build "pluggable" systems.

		@@ -1,23 +1,108 @@
		.. pluggy documentation master file, created by

Sphinx docs #39

Sphinx docs #39

Conversation

goodboy commented Jan 31, 2017 • edited Loading

nicoddemus left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

goodboy Feb 1, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

goodboy commented Feb 1, 2017 • edited Loading

nicoddemus commented Feb 1, 2017

Choose a reason for hiding this comment

nicoddemus commented Feb 1, 2017

hpk42 commented Feb 1, 2017

goodboy commented Feb 1, 2017

hpk42 commented Feb 2, 2017 via email

goodboy commented Feb 3, 2017

goodboy commented Feb 3, 2017

goodboy commented Feb 4, 2017

goodboy commented Feb 5, 2017

nicoddemus left a comment

Choose a reason for hiding this comment

goodboy commented Feb 5, 2017

nicoddemus commented Feb 6, 2017

goodboy commented Feb 8, 2017

hpk42 commented Feb 8, 2017

goodboy commented Feb 8, 2017

goodboy commented Jan 31, 2017 •

edited

Loading

goodboy Feb 1, 2017 •

edited

Loading

goodboy commented Feb 1, 2017 •

edited

Loading