[pytest-dev] Documentation proposal

Brianna Laugher brianna.laugher at gmail.com
Mon Aug 7 18:44:30 EDT 2017

Yes thanks Daniele!

Daniele gave a great talk at PyCon Australia this past weekend about these
four different types of documentation and how they are different/similar:

Daniele referred to "Brianna's tutorial", which is the materials for a 3
hour tutorial that I gave at the conference. It doesn't have video, but the
materials are here:


The concept of the tutorial was to use a "starter" application and test
suite and build on/modify that. The application is

I have a lot of notes and feedback from giving the tutorial itself to feed
back to the pytest community (mainly around using pytest-bdd/splinter/Xvfb
on Windows and OSX), but I am still in recovery mode from the conference
itself so it will take me a little longer to write that up.


On 8 August 2017 at 02:07, Bruno Oliveira <nicoddemus at gmail.com> wrote:

> Hi Daniele,
> Thanks a lot for following up on this!
> I've pushed your branch up to pytest's repository and enabled building it
> on RTD so people can more easily take a look at it:
> https://docs.pytest.org/en/documentation-restructure/
> I did a quick glance and I like what I see so far. Having separate
> tutorial/how-to guides/reference documents seems like a great improvement
> because a common complain regarding pytest's docs was the fact that there
> was no clear distinction between those different types of documentation.
> From my part I'm +1 on continue to work on this. :)
> Cheers,
> Bruno.
> On Mon, Aug 7, 2017 at 2:50 AM Daniele Procida <daniele at vurt.org> wrote:
>> On Sat, Jul 15, 2017, Daniele Procida <daniele at vurt.org> wrote:
>> >I propose to restructure the pytest docmentation, according to this
>> >scheme <https://divio.com/blog/documentation> (the rationale for the
>> >scheme is described at length in that article).
>> Hi.
>> I have made a start on this since I first mentioned it at EuroPython.
>> You can see the work so far at <https://github.com/pytest-
>> dev/pytest/compare/master...evildmp:documentation-restructure?expand=1>
>> To try it out locally:
>> Clone my branch and get into the right directory:
>>     git clone -b documentation-restructure git at github.com:evildmp/pytest.
>> git
>>     cd pytest/doc/en
>> Set up the virtualenv for the docs:
>>     make install
>> Start the documentation server:
>>     make run
>> Checkout the new documentation at <http://localhost:8001>.
>> Please note that there remains a lot more to do, but there is enough so
>> far to get an idea of:
>> * how it will be structured
>> * what it will like
>> I have many questions, which are in issues on my fork: <
>> https://github.com/evildmp/pytest/issues/>.
>> Because commits land so fast in master (over 200 since I started working
>> on this less than a month ago) it would be good to get some feedback on
>> this and know whether this approach is going to be accepted into pytest. If
>> so, I will be able to continue, with two main tasks:
>> * build Brianna's tutorial into the documentation
>> * work through every single page and ensure that all content is correctly
>> placed in the appropriate section.
>> Thanks,
>> Daniele
>> _______________________________________________
>> pytest-dev mailing list
>> pytest-dev at python.org
>> https://mail.python.org/mailman/listinfo/pytest-dev
> _______________________________________________
> pytest-dev mailing list
> pytest-dev at python.org
> https://mail.python.org/mailman/listinfo/pytest-dev

They've just been waiting in a mountain for the right moment:
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/pytest-dev/attachments/20170808/243eace6/attachment.html>

More information about the pytest-dev mailing list