[pytest-dev] Documentation proposal

[Bruno Oliveira]

Daniele,

I think nobody is against this refactoring, so please go ahead and let us
know of the progress. I sent you an invite as a collaborator of the pytest
repository so I think you can continue your work by pushing your changes
directly to the pytest-dev/pytest at documentation-restructure branch. This
will automatically rebuild the documentation which we can use for easier
reviewing it.

Raphael and Brianna,

What should we do with the reorganize-docs branch that was created during
the sprint?

Cheers,
Bruno.


On Mon, Aug 7, 2017 at 7:44 PM Brianna Laugher <brianna.laugher at gmail.com>
wrote:

> 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:
> https://www.youtube.com/watch?v=t4vKPhjcMZg&list=PLs4CJRBY5F1KsK4AbFaPsUT8X8iXc7X84&index=65
>
> 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:
>
> https://www.dropbox.com/sh/jx44jys7g6v5gy8/AAB49nqGd4_FXUqq6SjN4V6wa?dl=0
>
> The concept of the tutorial was to use a "starter" application and test
> suite and build on/modify that. The application is
> https://github.com/pfctdayelise/allseasons
>
> 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.
>
> cheers
> Brianna
>
>
> 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:
> http://modernthings.org/
> _______________________________________________
> pytest-dev mailing list
> pytest-dev at python.org
> https://mail.python.org/mailman/listinfo/pytest-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/pytest-dev/attachments/20170811/71731aa1/attachment.html>