Mailman 3 Helping with website improvements - NumPy-Discussion

newer
converting a C bytes array to two...

Helping with website improvements

older
numpy.org website redesign proposal

Dashamir Hoxha

15 Jul 2019 15 Jul '19

10:48 p.m.

Hi, With respect to this call for contributions: https://github.com/numpy/numpy/pull/13988/files I would like to help with improving the website of numpy (and maybe scipy as well). I have also applied for the Google Season of Docs 2019, and if accepted, I will be starting by the beginning of August. The improvements that I would like to make include: - Making the website responsive (so that it looks nice on small screens as well). There are responsive themes for sphinx and I may use one of them. - Improving the main page (or the landing page) so that it looks a bit more modern and attractive. - Reorganizing the structure of the information on the website, so that people from different backgrounds (students, professionals, etc.) can find more easily the relevant information that they are looking for. Including references to the external tutorials or courses about NumPy/SciPy. Other tentative improvements may be these: - Reorganize the docs so that each major release has its own version of docs. Major releases are those that may introduce new features, or in general, changes in the API (minor releases are the maintenance releases, which fix bugs, or make small changes, for example to improve the efficiency, but do not change the API). For example major releases may be v1.15, v1.16, v1.17 (however I am not sure about this). - Reorganize the docs so that the core API functionality is shown more prominently than the rest, and so that functions that may be deprecated in the future can be marked so (in order to discourage users from using them) and alternative solutions are suggested instead of them, etc. - Allow the users to add comments for each function or package. These may be usage examples for the benefit of other users, or pitfall alerts, or even bug reports. Reporting bugs on GitHub is better of course, but this may be a bit easier for the users. Since these are not incremental changes, if may be better if I work on a fork of the website repository, until they are finished and the new website is ready. Regards, Dashamir Hoxha

Attachments:

attachment.htm (text/html — 2.3 KB)

Show replies by date

Dashamir Hoxha

16 Jul 16 Jul

7:22 a.m.

On Tue, Jul 16, 2019 at 12:48 AM Dashamir Hoxha wrote:

...

Hi,

With respect to this call for contributions: https://github.com/numpy/numpy/pull/13988/files I would like to help with improving the website of numpy (and maybe scipy as well). I have also applied for the Google Season of Docs 2019, and if accepted, I will be starting by the beginning of August.

The improvements that I would like to make include: - Making the website responsive (so that it looks nice on small screens as well). There are responsive themes for sphinx and I may use one of them. - Improving the main page (or the landing page) so that it looks a bit more modern and attractive. - Reorganizing the structure of the information on the website, so that people from different backgrounds (students, professionals, etc.) can find more easily the relevant information that they are looking for. Including references to the external tutorials or courses about NumPy/SciPy.

Has anybody tried Katacoda before: https://www.katacoda.com/courses/python/playground ? It can be used to develop interactive tutorials, which can also be embedded on a web page. I may also write a couple of beginners' tutorials (based on the existing tutorials), if this seems to be useful.

...

Other tentative improvements may be these: - Reorganize the docs so that each major release has its own version of docs. Major releases are those that may introduce new features, or in general, changes in the API (minor releases are the maintenance releases, which fix bugs, or make small changes, for example to improve the efficiency, but do not change the API). For example major releases may be v1.15, v1.16, v1.17 (however I am not sure about this). - Reorganize the docs so that the core API functionality is shown more prominently than the rest, and so that functions that may be deprecated in the future can be marked so (in order to discourage users from using them) and alternative solutions are suggested instead of them, etc. - Allow the users to add comments for each function or package. These may be usage examples for the benefit of other users, or pitfall alerts, or even bug reports. Reporting bugs on GitHub is better of course, but this may be a bit easier for the users.

Since these are not incremental changes, if may be better if I work on a fork of the website repository, until they are finished and the new website is ready.

Regards, Dashamir Hoxha

Ralf Gommers

17 Jul 17 Jul

4:10 a.m.

On Tue, Jul 16, 2019 at 12:23 AM Dashamir Hoxha wrote:

...

On Tue, Jul 16, 2019 at 12:48 AM Dashamir Hoxha wrote:

...
Hi,

With respect to this call for contributions: https://github.com/numpy/numpy/pull/13988/files I would like to help with improving the website of numpy (and maybe scipy as well). I have also applied for the Google Season of Docs 2019, and if accepted, I will be starting by the beginning of August.

The improvements that I would like to make include: - Making the website responsive (so that it looks nice on small screens as well). There are responsive themes for sphinx and I may use one of them. - Improving the main page (or the landing page) so that it looks a bit more modern and attractive. - Reorganizing the structure of the information on the website, so that people from different backgrounds (students, professionals, etc.) can find more easily the relevant information that they are looking for. Including references to the external tutorials or courses about NumPy/SciPy.

Has anybody tried Katacoda before: https://www.katacoda.com/courses/python/playground ?

I haven't heard of it before. Looks cool. Seems to run on Docker, so would require some infrastructure. If it's something we could get from a static site, then it may be worth considering. Could you summarize what it would require? Cheers, Ralf It can be used to develop interactive tutorials, which can also be embedded

...

on a web page. I may also write a couple of beginners' tutorials (based on the existing tutorials), if this seems to be useful.

Dashamir Hoxha

12:28 p.m.

On Wed, Jul 17, 2019 at 6:11 AM Ralf Gommers wrote:

...

...
Has anybody tried Katacoda before: https://www.katacoda.com/courses/python/playground ?

I haven't heard of it before. Looks cool. Seems to run on Docker, so would require some infrastructure. If it's something we could get from a static site, then it may be worth considering. Could you summarize what it would require?

The infrastructure is supplied by Katacoda, we don't need to run or maintain any server (although I don't think this would be a big problem). And it is free. The only limitation is that the duration of the training session for a student is 1 hour (and then he can reload the browser and start a fresh session). If enterprises or training companies would like to lift this limitation, they have to contact them. Building an interactive tutorial is very easy and everybody can learn it in a short time. The code of the tutorial is just a bunch of json and markdown files (for the configuration of the environment and for the steps of the tutorial). It can be saved on your preferred git repository (GitHub, GitLab, Bitbacket, etc.) and katacoda pulls it from there and builds the tutorial environment (docker image). Here is a minimal (hello world) example: https://github.com/dashohoxha/katacoda-scenarios/tree/master/hello-world You also need to set a webhook on the repository, so that whenever you make some changes (commits) katacoda is notified to refresh the content of the tutorial. Regards, Dashamir

Ralf Gommers

9:43 p.m.

On Wed, Jul 17, 2019 at 7:29 AM Dashamir Hoxha wrote:

...

On Wed, Jul 17, 2019 at 6:11 AM Ralf Gommers wrote:

...
...
Has anybody tried Katacoda before: https://www.katacoda.com/courses/python/playground ?

I haven't heard of it before. Looks cool. Seems to run on Docker, so would require some infrastructure. If it's something we could get from a static site, then it may be worth considering. Could you summarize what it would require?

The infrastructure is supplied by Katacoda, we don't need to run or maintain any server (although I don't think this would be a big problem). And it is free. The only limitation is that the duration of the training session for a student is 1 hour (and then he can reload the browser and start a fresh session). If enterprises or training companies would like to lift this limitation, they have to contact them.

Building an interactive tutorial is very easy and everybody can learn it in a short time. The code of the tutorial is just a bunch of json and markdown files (for the configuration of the environment and for the steps of the tutorial). It can be saved on your preferred git repository (GitHub, GitLab, Bitbacket, etc.) and katacoda pulls it from there and builds the tutorial environment (docker image). Here is a minimal (hello world) example: https://github.com/dashohoxha/katacoda-scenarios/tree/master/hello-world You also need to set a webhook on the repository, so that whenever you make some changes (commits) katacoda is notified to refresh the content of the tutorial.

That sounds good to me. I believe SymPy is also pretty happy with their interactive terminal embedded in their website. Could you create a new issue on https://github.com/numpy/numpy.org/issues? It would be good to start keeping track of website improvement ideas - ideas in mailing list threads tend to get lost eventually. Thanks, Ralf

Dashamir Hoxha

18 Jul 18 Jul

9:17 a.m.

On Wed, Jul 17, 2019 at 11:45 PM Ralf Gommers wrote:

...

That sounds good to me. I believe SymPy is also pretty happy with their interactive terminal embedded in their website.

Could you create a new issue on https://github.com/numpy/numpy.org/issues? It would be good to start keeping track of website improvement ideas - ideas in mailing list threads tend to get lost eventually.

I have created it: https://github.com/numpy/numpy.org/issues/26 As a side note, I think that it would be nice if documentation issues are kept on this repo as well (or on their on repo), instead of discussing them on numpy/numpy. This would clearly distinguish them from the rest of the issues (bugs, features, enhancements, etc.). For example I am interested on the website and documentation issues, but I have to subscribe (watch) to numpy/numpy. As a result I get more than 100 notification messages a day, 90% of which I have to delete because I am not interested in them (actually I don't understand what is being discussed there). This is like a kind of innocent spam. A better classification of issues to different repositories may help to reduce this. Maybe the same should be done for scipy too. I have created another issue for discussing this: https://github.com/numpy/numpy.org/issues/27 Regards, Dashamir

Charles R Harris

16 Jul 16 Jul

1:06 p.m.

Hi Dashamir, On Mon, Jul 15, 2019 at 4:49 PM Dashamir Hoxha wrote:

...

Hi,

With respect to this call for contributions: https://github.com/numpy/numpy/pull/13988/files I would like to help with improving the website of numpy (and maybe scipy as well). I have also applied for the Google Season of Docs 2019, and if accepted, I will be starting by the beginning of August.

The improvements that I would like to make include: - Making the website responsive (so that it looks nice on small screens as well). There are responsive themes for sphinx and I may use one of them. - Improving the main page (or the landing page) so that it looks a bit more modern and attractive. - Reorganizing the structure of the information on the website, so that people from different backgrounds (students, professionals, etc.) can find more easily the relevant information that they are looking for. Including references to the external tutorials or courses about NumPy/SciPy.

Other tentative improvements may be these: - Reorganize the docs so that each major release has its own version of docs. Major releases are those that may introduce new features, or in general, changes in the API (minor releases are the maintenance releases, which fix bugs, or make small changes, for example to improve the efficiency, but do not change the API). For example major releases may be v1.15, v1.16, v1.17 (however I am not sure about this). - Reorganize the docs so that the core API functionality is shown more prominently than the rest, and so that functions that may be deprecated in the future can be marked so (in order to discourage users from using them) and alternative solutions are suggested instead of them, etc. - Allow the users to add comments for each function or package. These may be usage examples for the benefit of other users, or pitfall alerts, or even bug reports. Reporting bugs on GitHub is better of course, but this may be a bit easier for the users.

Since these are not incremental changes, if may be better if I work on a fork of the website repository, until they are finished and the new website is ready.

That sounds interesting and ambitious. I'll let others offer suggestions, we might want to host the site at a different provider which will offer easier access to developers. The repo is at at https://github.com/numpy/numpy.org. There is also a scipy.org https://github.com/scipy/scipy.org website that could also use some work. Chuck

Sebastian Berg

4:57 p.m.

On Tue, 2019-07-16 at 07:06 -0600, Charles R Harris wrote:

...

Hi Dashamir,

On Mon, Jul 15, 2019 at 4:49 PM Dashamir Hoxha wrote:

...
Hi,

With respect to this call for contributions: https://github.com/numpy/numpy/pull/13988/files I would like to help with improving the website of numpy (and maybe scipy as well). I have also applied for the Google Season of Docs 2019, and if accepted, I will be starting by the beginning of August.

The improvements that I would like to make include: - Making the website responsive (so that it looks nice on small screens as well). There are responsive themes for sphinx and I may use one of them. - Improving the main page (or the landing page) so that it looks a bit more modern and attractive. - Reorganizing the structure of the information on the website, so that people from different backgrounds (students, professionals, etc.) can find more easily the relevant information that they are looking for. Including references to the external tutorials or courses about NumPy/SciPy.

Other tentative improvements may be these: - Reorganize the docs so that each major release has its own version of docs. Major releases are those that may introduce new features, or in general, changes in the API (minor releases are the maintenance releases, which fix bugs, or make small changes, for example to improve the efficiency, but do not change the API). For example major releases may be v1.15, v1.16, v1.17 (however I am not sure about this). - Reorganize the docs so that the core API functionality is shown more prominently than the rest, and so that functions that may be deprecated in the future can be marked so (in order to discourage users from using them) and alternative solutions are suggested instead of them, etc. - Allow the users to add comments for each function or package. These may be usage examples for the benefit of other users, or pitfall alerts, or even bug reports. Reporting bugs on GitHub is better of course, but this may be a bit easier for the users.

Since these are not incremental changes, if may be better if I work on a fork of the website repository, until they are finished and the new website is ready.

That sounds interesting and ambitious. I'll let others offer suggestions, we might want to host the site at a different provider which will offer easier access to developers. The repo is at at https://github.com/numpy/numpy.org. There is also a scipy.org website that could also use some work.

Indeed, great to see interest, it sounds very nice! I believe you are already in contact with Ralf directly (just in case someone wonders if there might be little immediate followup on the mailing list). Best, Sebastian

...

Chuck _______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion

Ralf Gommers

17 Jul 17 Jul

4:06 a.m.

On Tue, Jul 16, 2019 at 9:57 AM Sebastian Berg wrote:

...

On Tue, 2019-07-16 at 07:06 -0600, Charles R Harris wrote:

...
Hi Dashamir,

On Mon, Jul 15, 2019 at 4:49 PM Dashamir Hoxha wrote:

...
Hi,

With respect to this call for contributions: https://github.com/numpy/numpy/pull/13988/files I would like to help with improving the website of numpy (and maybe scipy as well).

Thanks for offering to help Dashamir!

...

...
I have also applied for the Google Season of Docs 2019, and if

...
accepted, I will be starting by the beginning of August.

The improvements that I would like to make include: - Making the website responsive (so that it looks nice on small screens as well). There are responsive themes for sphinx and I may use one of them. - Improving the main page (or the landing page) so that it looks a bit more modern and attractive. - Reorganizing the structure of the information on the website, so that people from different backgrounds (students, professionals, etc.) can find more easily the relevant information that they are looking for. Including references to the external tutorials or courses about NumPy/SciPy.

This all sounds good. I just sent another email about the numpy.org redesign, please feel free to jump in on the proposal ( https://github.com/numpy/numpy/pull/14032).

...

...
...
Other tentative improvements may be these: - Reorganize the docs so that each major release has its own version of docs. Major releases are those that may introduce new features, or in general, changes in the API (minor releases are the maintenance releases, which fix bugs, or make small changes, for example to improve the efficiency, but do not change the API). For example major releases may be v1.15, v1.16, v1.17 (however I am not sure about this).

Note that the docs are kept separate from the numpy.org site, and when we move numpy.org away from Sphinx that separation will be clearer. Matti is already working on this multi-version reshuffle in https://github.com/numpy/numpy/pull/13886.

...

...
...
- Reorganize the docs so that the core API functionality is shown more prominently than the rest, and so that functions that may be deprecated in the future can be marked so (in order to discourage users from using them) and alternative solutions are suggested instead of them, etc.

This is a good idea. That sounds more like a GSoD topic - it's quite some work to do, and to agree on the choices of what's important.

...

...
- Allow the users to add comments for each function or package.

...
These may be usage examples for the benefit of other users, or pitfall alerts, or even bug reports. Reporting bugs on GitHub is better of course, but this may be a bit easier for the users.

This one I'm not so sure about. Could result in a lot more work for us......

...

...
...
Since these are not incremental changes, if may be better if I work on a fork of the website repository, until they are finished and the new website is ready.

Yes, would be good to start in a clean repo. I'd like to get the NEP accepted first, and then put together a bit of a plan so multiple people can work together on this. Cheers, Ralf

...

...
...
That sounds interesting and ambitious. I'll let others offer suggestions, we might want to host the site at a different provider which will offer easier access to developers. The repo is at at https://github.com/numpy/numpy.org. There is also a scipy.org website that could also use some work.

Indeed, great to see interest, it sounds very nice! I believe you are already in contact with Ralf directly (just in case someone wonders if there might be little immediate followup on the mailing list).

Best,

Sebastian

...
Chuck _______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion

NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion

1743

Age (days ago)

1746

Last active (days ago)

List overview

Download

8 comments

4 participants

participants (4)

Charles R Harris
Dashamir Hoxha
Ralf Gommers
Sebastian Berg

Helping with website improvements

Dashamir Hoxha

Dashamir Hoxha

Ralf Gommers

Dashamir Hoxha

Ralf Gommers

Dashamir Hoxha

Charles R Harris

Sebastian Berg

Ralf Gommers

tags

participants (4)