Re: [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@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 
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=PLs4CJRBY5F1KsK4AbFaPsUT8X8iXc7X84=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  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  wrote:
>>
>>> On Sat, Jul 15, 2017, Daniele Procida  wrote:
>>>
>>> >I propose to restructure the pytest docmentation, according to this
>>> >scheme  (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 g...@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 .
>>>
>>> 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@python.org
>>> https://mail.python.org/mailman/listinfo/pytest-dev
>>>
>>
>> ___
>> pytest-dev mailing list
>> pytest-dev@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@python.org
> https://mail.python.org/mailman/listinfo/pytest-dev
>
___
pytest-dev mailing list
pytest-dev@python.org
https://mail.python.org/mailman/listinfo/pytest-dev

Re: [pytest-dev] Documentation proposal

[Brianna Laugher]

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=PLs4CJRBY5F1KsK4AbFaPsUT8X8iXc7X84=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  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  wrote:
>
>> On Sat, Jul 15, 2017, Daniele Procida  wrote:
>>
>> >I propose to restructure the pytest docmentation, according to this
>> >scheme  (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 > 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 g...@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 .
>>
>> 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@python.org
>> https://mail.python.org/mailman/listinfo/pytest-dev
>>
>
> ___
> pytest-dev mailing list
> pytest-dev@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@python.org
https://mail.python.org/mailman/listinfo/pytest-dev

Re: [pytest-dev] Documentation proposal

[Bruno Oliveira]

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  wrote:

> On Sat, Jul 15, 2017, Daniele Procida  wrote:
>
> >I propose to restructure the pytest docmentation, according to this
> >scheme  (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 g...@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 .
>
> 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@python.org
> https://mail.python.org/mailman/listinfo/pytest-dev
>
___
pytest-dev mailing list
pytest-dev@python.org
https://mail.python.org/mailman/listinfo/pytest-dev

Re: [pytest-dev] Documentation proposal

[Carol Willing]

Nice!

Just an FYI for those that use conda (and not virtualenv)... if you edit the 
Makefile html section and delete the portion of the line before sphinx-build 
then you can install the requirements.txt via pip, and build with make html.

Where do you want suggestions filed? I saw a few minor things such as Tutorial 
labeled as "Tutorial" in some places and "Introduction" in others. Breaking out 
the changelog to its own highlevel section would declutter the About section.

Thanks for doing this. We enjoy using pytest at Project Jupyter.

Carol

Carol Willing

Research Software Engineer
Project Jupyter at Cal Poly SLO

Signature Strengths
Empathy - Relator - Ideation - Strategic - Learner


> On Aug 6, 2017, at 10:49 PM, Daniele Procida  wrote:
> 
> On Sat, Jul 15, 2017, Daniele Procida  wrote:
> 
>> I propose to restructure the pytest docmentation, according to this
>> scheme  (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 
> 
> 
> To try it out locally:
> 
> Clone my branch and get into the right directory:
> 
>git clone -b documentation-restructure g...@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 .
> 
> 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: 
> . 
> 
> 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@python.org
> https://mail.python.org/mailman/listinfo/pytest-dev

___
pytest-dev mailing list
pytest-dev@python.org
https://mail.python.org/mailman/listinfo/pytest-dev

Re: [pytest-dev] Documentation proposal

[Daniele Procida]

On Sat, Jul 15, 2017, Daniele Procida  wrote:

>I propose to restructure the pytest docmentation, according to this
>scheme  (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 


To try it out locally:

Clone my branch and get into the right directory:

git clone -b documentation-restructure g...@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 .

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: 
. 

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@python.org
https://mail.python.org/mailman/listinfo/pytest-dev

Re: [pytest-dev] Documentation proposal

[Floris Bruynooghe]

Hi Daniele,

On 15 July 2017 at 12:32, Daniele Procida  wrote:
> Dear pytest developers,
>
> I have been speaking to Raphael Pierzina at EuroPython.
>
> I propose to restructure the pytest docmentation, according to this scheme 
>  (the rationale for the scheme is 
> described at length in that article).
>
> The documention already contains most of the content it requires, but I think 
> it could be hugely improved by restructuring it.

This sounds great!  From my point of view this would certainly be
welcome, the navigability of our documentation is a long-standing
issue which could do with improving.

> I'd also change the Sphinx theme to the RTD theme, which improves navigation.

I'd be a little sad to see us unified and conform to everyone else's
look and to loose the logo.  Which bits of navigation are you aiming
to improve?  Would it be possible to do with some refactoring of the
contents and layout of the box on the left?  We could always reach out
to Tobias who did the last themes updates (IIRC) to see if he'd like
fix this.

> Would this be welcome?

Certainly!

Cheers,
Floris
___
pytest-dev mailing list
pytest-dev@python.org
https://mail.python.org/mailman/listinfo/pytest-dev