[SciPy-User] GSoD - Technical Writter

[Ralf Gommers]

On Sat, May 18, 2019 at 4:52 PM Gael Varoquaux <
gael.varoquaux at normalesup.org> wrote:

> On Sat, May 18, 2019 at 04:40:50PM +0200, Ralf Gommers wrote:
> > You're right, the interface is a little outdated. Docs will have to stay
> in
> > Sphinx (that's really the only choice for reST docs for a large Python
> > package), however the top level websites (scipy.org, docs.scipy.org)
> could be
> > moved to Jekyll or Hugo for a more modern look - this will actually be
> > beneficial.
>
> Sphinx uses standard web tools as outputs (the jinja templating engine,
> for instance). This problem, to me, is a theming problem: templating +
> CSS. In scipy-lectures, I had done some work to build a theme that is
> mobile friendly. More generally, I think that there would be value in
> maintaining these themes in a way that can be shared across project.
> Sphinx does have modern themes, such as
> https://alabaster.readthedocs.io/en/latest/


Hey Gael, I think you're mostly right that it's about theming, but not
completely. Alabaster isn't really the kind of theme that helps. It's still
for docs. For a modern website, Sphinx is just not a great tool. I'd love
something like https://jupyter.org/ or https://julialang.org/, and then a
Sphinx site under it for user and reference guides. I don't think Sphinx is
the right tool for the job of building a modern top-level site.


>
>
>
> > Yes, there's https://scipy-lectures.org/ for example. Guiding users
> effectively
> > to all existing resources will be a major step forward.
>
> Glad to see some synergy here!
>

Perhaps there should be even more synergy. Scipy-lectures and
http://scipy.github.io/devdocs/tutorial/index.html partly overlap in
content and scope, separating them better could help users and get us more
good-quality material with less effort. I just don't know what the split
should be. Any thoughts?

Cheers,
Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-user/attachments/20190518/88d27b88/attachment-0001.html>