Re: Google Summer of Docs Faq and Tutorial Proposed Structure .

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: Google Summer of Docs Faq and Tutorial Proposed Structure .

Saber Tooth
Hello Melissa ,
I have altered and built upon my previous proposal , if you could take a few minutes to read it it would be great . I have tried to explain the sections we had discussed in the meeting on 22 June . 

Moreover as per your feedback , I would like to start contributing to the docs and start building the docs in my Linux environment .

Best ,
Mrinal Tyagi 


On Wed, 24 Jun 2020 at 2:36 PM, Saber Tooth <[hidden email]> wrote:
Hello Melissa and all the Mentors  ,

In the last meeting of NumPy Docs held on June 22nd , I had Proposed Tutorial and Faqs structure , where it was discussed how we should include them in the new structured Documentation .
Now after a lot of Googling I have been able to provide a structured solution 
It is very important for us to include the FAQs section , but why ?
If we see how many views some questions on Stack overflow https://stackoverflow.com/questions/tagged/numpy?tab=frequent&page=1&pagesize=15  have got the answer is obvious , the 1st page itself has garnered some 4-5 million views and there are really many questions . It means if we are able to answer some of these questions ,not necessarily the exact questions , it would be really good for the Docs .

I have tried to break the FAQs page into sections so that everything is not cramped onto one page and we have good docs as per SEO guidelines .
I have structured based on best practices for the FAQs section : https://www.shivarweb.com/9665/faq-page-best-practices/ .

I have improved further upon my previous proposal , please have a look.
Eagerly waiting [hidden email] [hidden email]  for your feedback on the same , I would be obliged if you have some ideas which could be incorporated with the same or built upon these .






Thanks ,
Mrinal Tyagi

_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
Reply | Threaded
Open this post in threaded view
|

Re: Google Summer of Docs Faq and Tutorial Proposed Structure .

Saber Tooth
Hi Melissa ,
I have been trying to follow https://numpy.org/devdocs/dev/index.html and build docs , i am not able to execute the building albeit following the exact guidelines.
Is there a slack channel for this as i'd be able to better explain / resolve it there , till then :

I have tried make html command after adhering to the above link
Error when i haven't switched it to required git version :

installed numpy 32f514f546 != current repo git version '3cf4c28906'
use "make dist" or "GITVER=32f514f546 make html ..."
Makefile:93: recipe for target 'version-check' failed
make: *** [version-check] Error 1

Now when i make it work as per my installed numpy version :

There are quite a lot of warnings and many problems like :

document isn't included in any toctree
failed to import 'numpy.polynomial.set_default_printstyle': no module named numpy.polynomial.set_default_printstyle
WARNING: autodoc: failed to import module 'typing' from module 'numpy'; the following exception was raised:
No module named 'numpy.typing'

Many modules were missing which gave a warning ,

Now maybe the errors are coming in just my workspace , but I have tried reinstalling everything , got the latest version of cython too .

It would be really helpful for me if you are able to give me some advice , or a workaround for the problem 

On Fri, 26 Jun 2020 at 01:39, Melissa Mendonça <[hidden email]> wrote:
Hello Mrinal,

I don't think I have any other specific issues to comment on your proposal. The mentors will analyze all proposals after July 9th.

If you want to start contributing to the docs, you are welcome. You can check the Contributor Guide (https://numpy.org/devdocs/dev/index.html), How to contribute documentation (https://numpy.org/devdocs/dev/howto-docs.html) and the current documentation.

Thanks,

Melissa

On Thu, Jun 25, 2020 at 2:27 PM Saber Tooth <[hidden email]> wrote:
Hello Melissa ,
I have altered and built upon my previous proposal , if you could take a few minutes to read it it would be great . I have tried to explain the sections we had discussed in the meeting on 22 June . 

Moreover as per your feedback , I would like to start contributing to the docs and start building the docs in my Linux environment .

Best ,
Mrinal Tyagi 


On Wed, 24 Jun 2020 at 2:36 PM, Saber Tooth <[hidden email]> wrote:
Hello Melissa and all the Mentors  ,

In the last meeting of NumPy Docs held on June 22nd , I had Proposed Tutorial and Faqs structure , where it was discussed how we should include them in the new structured Documentation .
Now after a lot of Googling I have been able to provide a structured solution 
It is very important for us to include the FAQs section , but why ?
If we see how many views some questions on Stack overflow https://stackoverflow.com/questions/tagged/numpy?tab=frequent&page=1&pagesize=15  have got the answer is obvious , the 1st page itself has garnered some 4-5 million views and there are really many questions . It means if we are able to answer some of these questions ,not necessarily the exact questions , it would be really good for the Docs .

I have tried to break the FAQs page into sections so that everything is not cramped onto one page and we have good docs as per SEO guidelines .
I have structured based on best practices for the FAQs section : https://www.shivarweb.com/9665/faq-page-best-practices/ .

I have improved further upon my previous proposal , please have a look.
Eagerly waiting [hidden email] [hidden email]  for your feedback on the same , I would be obliged if you have some ideas which could be incorporated with the same or built upon these .






Thanks ,
Mrinal Tyagi

_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
Reply | Threaded
Open this post in threaded view
|

Re: Google Summer of Docs Faq and Tutorial Proposed Structure .

Saber Tooth
Hello Melissa ,
Just read your email regarding docs meeting ,
I have now also tried to use https://bjnath.github.io/demodocs/new_docs_dev as a way to build docs , they were really useful for me as now i have got the message "build succeeded.

The HTML pages are in build/html." .

I believe we can really replace  https://numpy.org/devdocs/dev/index.html with  https://bjnath.github.io/demodocs/new_docs_dev , the former being incomplete  and sometimes misleading .
I can now really start on with contributing to NumPy having done my Development setup .
I would also like to ask what are the fields in NumPy Docs that u would really like me to contribute to ,
should i be doing as per my proposal or an issue ?

Looking forward to hearing from you
Best,
Mrinal 

On Fri, 3 Jul 2020 at 18:49, Saber Tooth <[hidden email]> wrote:
Hi Melissa ,
I have been trying to follow https://numpy.org/devdocs/dev/index.html and build docs , i am not able to execute the building albeit following the exact guidelines.
Is there a slack channel for this as i'd be able to better explain / resolve it there , till then :

I have tried make html command after adhering to the above link
Error when i haven't switched it to required git version :

installed numpy 32f514f546 != current repo git version '3cf4c28906'
use "make dist" or "GITVER=32f514f546 make html ..."
Makefile:93: recipe for target 'version-check' failed
make: *** [version-check] Error 1

Now when i make it work as per my installed numpy version :

There are quite a lot of warnings and many problems like :

document isn't included in any toctree
failed to import 'numpy.polynomial.set_default_printstyle': no module named numpy.polynomial.set_default_printstyle
WARNING: autodoc: failed to import module 'typing' from module 'numpy'; the following exception was raised:
No module named 'numpy.typing'

Many modules were missing which gave a warning ,

Now maybe the errors are coming in just my workspace , but I have tried reinstalling everything , got the latest version of cython too .

It would be really helpful for me if you are able to give me some advice , or a workaround for the problem 

On Fri, 26 Jun 2020 at 01:39, Melissa Mendonça <[hidden email]> wrote:
Hello Mrinal,

I don't think I have any other specific issues to comment on your proposal. The mentors will analyze all proposals after July 9th.

If you want to start contributing to the docs, you are welcome. You can check the Contributor Guide (https://numpy.org/devdocs/dev/index.html), How to contribute documentation (https://numpy.org/devdocs/dev/howto-docs.html) and the current documentation.

Thanks,

Melissa

On Thu, Jun 25, 2020 at 2:27 PM Saber Tooth <[hidden email]> wrote:
Hello Melissa ,
I have altered and built upon my previous proposal , if you could take a few minutes to read it it would be great . I have tried to explain the sections we had discussed in the meeting on 22 June . 

Moreover as per your feedback , I would like to start contributing to the docs and start building the docs in my Linux environment .

Best ,
Mrinal Tyagi 


On Wed, 24 Jun 2020 at 2:36 PM, Saber Tooth <[hidden email]> wrote:
Hello Melissa and all the Mentors  ,

In the last meeting of NumPy Docs held on June 22nd , I had Proposed Tutorial and Faqs structure , where it was discussed how we should include them in the new structured Documentation .
Now after a lot of Googling I have been able to provide a structured solution 
It is very important for us to include the FAQs section , but why ?
If we see how many views some questions on Stack overflow https://stackoverflow.com/questions/tagged/numpy?tab=frequent&page=1&pagesize=15  have got the answer is obvious , the 1st page itself has garnered some 4-5 million views and there are really many questions . It means if we are able to answer some of these questions ,not necessarily the exact questions , it would be really good for the Docs .

I have tried to break the FAQs page into sections so that everything is not cramped onto one page and we have good docs as per SEO guidelines .
I have structured based on best practices for the FAQs section : https://www.shivarweb.com/9665/faq-page-best-practices/ .

I have improved further upon my previous proposal , please have a look.
Eagerly waiting [hidden email] [hidden email]  for your feedback on the same , I would be obliged if you have some ideas which could be incorporated with the same or built upon these .






Thanks ,
Mrinal Tyagi

_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
Reply | Threaded
Open this post in threaded view
|

Re: Google Summer of Docs Faq and Tutorial Proposed Structure .

Melissa Mendonça
Hello Mrinal,

That is indeed something we are looking at. Feel free to join the discussion at the documentation meeting on Monday, or here if you'd like. I don't think Ben has opened an issue or PR about this yet, but if he does the link will surely be at the hackmd document for the docs meeting (here: https://hackmd.io/oB_boakvRqKR-_2jRV-Qjg)

About contributing, you can start by issues that you feel are interesting to you, or even opening new ones, such as https://github.com/numpy/numpy/issues/15760 and https://github.com/numpy/numpy/issues/15793, for example. If you need help you can tag me on the specific issue and I'll try to answer to the best of my abilities.

About the GSoD proposal, keep in mind that the period for the evaluation of projects starts on July 9. We've had a large number of people interested in the project, so there are no guarantees at this point that your project will be chosen. If you want to work on your project anyway, feel free!

Best,

- Melissa

On Fri, Jul 3, 2020 at 12:22 PM Saber Tooth <[hidden email]> wrote:
Hello Melissa ,
Just read your email regarding docs meeting ,
I have now also tried to use https://bjnath.github.io/demodocs/new_docs_dev as a way to build docs , they were really useful for me as now i have got the message "build succeeded.

The HTML pages are in build/html." .

I believe we can really replace  https://numpy.org/devdocs/dev/index.html with  https://bjnath.github.io/demodocs/new_docs_dev , the former being incomplete  and sometimes misleading .
I can now really start on with contributing to NumPy having done my Development setup .
I would also like to ask what are the fields in NumPy Docs that u would really like me to contribute to ,
should i be doing as per my proposal or an issue ?

Looking forward to hearing from you
Best,
Mrinal 

On Fri, 3 Jul 2020 at 18:49, Saber Tooth <[hidden email]> wrote:
Hi Melissa ,
I have been trying to follow https://numpy.org/devdocs/dev/index.html and build docs , i am not able to execute the building albeit following the exact guidelines.
Is there a slack channel for this as i'd be able to better explain / resolve it there , till then :

I have tried make html command after adhering to the above link
Error when i haven't switched it to required git version :

installed numpy 32f514f546 != current repo git version '3cf4c28906'
use "make dist" or "GITVER=32f514f546 make html ..."
Makefile:93: recipe for target 'version-check' failed
make: *** [version-check] Error 1

Now when i make it work as per my installed numpy version :

There are quite a lot of warnings and many problems like :

document isn't included in any toctree
failed to import 'numpy.polynomial.set_default_printstyle': no module named numpy.polynomial.set_default_printstyle
WARNING: autodoc: failed to import module 'typing' from module 'numpy'; the following exception was raised:
No module named 'numpy.typing'

Many modules were missing which gave a warning ,

Now maybe the errors are coming in just my workspace , but I have tried reinstalling everything , got the latest version of cython too .

It would be really helpful for me if you are able to give me some advice , or a workaround for the problem 

On Fri, 26 Jun 2020 at 01:39, Melissa Mendonça <[hidden email]> wrote:
Hello Mrinal,

I don't think I have any other specific issues to comment on your proposal. The mentors will analyze all proposals after July 9th.

If you want to start contributing to the docs, you are welcome. You can check the Contributor Guide (https://numpy.org/devdocs/dev/index.html), How to contribute documentation (https://numpy.org/devdocs/dev/howto-docs.html) and the current documentation.

Thanks,

Melissa

On Thu, Jun 25, 2020 at 2:27 PM Saber Tooth <[hidden email]> wrote:
Hello Melissa ,
I have altered and built upon my previous proposal , if you could take a few minutes to read it it would be great . I have tried to explain the sections we had discussed in the meeting on 22 June . 

Moreover as per your feedback , I would like to start contributing to the docs and start building the docs in my Linux environment .

Best ,
Mrinal Tyagi 


On Wed, 24 Jun 2020 at 2:36 PM, Saber Tooth <[hidden email]> wrote:
Hello Melissa and all the Mentors  ,

In the last meeting of NumPy Docs held on June 22nd , I had Proposed Tutorial and Faqs structure , where it was discussed how we should include them in the new structured Documentation .
Now after a lot of Googling I have been able to provide a structured solution 
It is very important for us to include the FAQs section , but why ?
If we see how many views some questions on Stack overflow https://stackoverflow.com/questions/tagged/numpy?tab=frequent&page=1&pagesize=15  have got the answer is obvious , the 1st page itself has garnered some 4-5 million views and there are really many questions . It means if we are able to answer some of these questions ,not necessarily the exact questions , it would be really good for the Docs .

I have tried to break the FAQs page into sections so that everything is not cramped onto one page and we have good docs as per SEO guidelines .
I have structured based on best practices for the FAQs section : https://www.shivarweb.com/9665/faq-page-best-practices/ .

I have improved further upon my previous proposal , please have a look.
Eagerly waiting [hidden email] [hidden email]  for your feedback on the same , I would be obliged if you have some ideas which could be incorporated with the same or built upon these .






Thanks ,
Mrinal Tyagi

_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion