Hi David Your input is highly appreciated and I invite more users to give their 2 cents on this issue :),
My comments to your comments below I think one very important aspect is maintainability, and documentation of > the system you would put into place. This is especially important in case > the maintainer of the site, that seems to be you, wants to hand over the > work to someone else. In that sense the Github pages + static site > generator (Pelican) is, in my humble opinion, a very good choice: plenty of > documented examples are floating around on the web, and people can easily > learn how to use it and deploy/update the site (I also run Github-pages + > pelican for my personal rather inactive blog). > Maintainability is of course crucial and a great thing to have in mind! The more I use Pelican the more I like it, it is quite simple to get going and also extend if necessary. Already the amount of plugins for it is great and seem to be growing. > I have not used Readthedocs so I can't comment on how easy/difficult it is > to use. Although I agree with your argument against using an external site > for the documentation, I think the advantages you name are very very strong > points indeed (build hooks, docs for older versions). The easier it is to > maintain (automatic build hooks for the different supported versions), the > better. You could become bored quickly when maintaining the > website/documentation builds is too laborious. > I tried read the docs following this tutorial <https://www.youtube.com/watch?v=QNHM7q2hLh8> and it works great, I like all the advantages that read the docs offer but I really dislike that all this read the docs documentation websites look the same... which might be practical but it is super boring... at least is how I see it from the casual user perspective. *<RANT>* *I hate websites that have a "main website" with links that lead to a different looking website!!!! (yes tortoise-hg <http://tortoisehg.bitbucket.org/>, I am talking to you!), I mean what is the point of making these websites "main pages" if all "falls apart"on every single click.... hey now I am in readthedocs and I did not bother to use the same colors of the project, hey here is bitbucket and the bitbucket wiki and hey tutotial link, what? back to read the docs...! yuk!* *</RANT>* In terms of the maintenance overload, I must say the overburden of having the docs hosted in site would be minimal once the setup is ready (even for multiple versions), it would limit to running a fabfile script (using fabric) that would grab the specific versions of spyder (based on git tags) run sphinx for each version and dump the output to the content folder of Pelican and then run pelican, and then push the result to the repo in github. Of course this would need to recreate the tags for the versions that we will support on the future, and this would have to be done once the migration is complete. The idea is that spyder users should always use the latest version... but some API's change ipython Qt...PyQt, so it might be inevitable that on our desire to be up to date with all the other libraries we depend on, we might break something that ours users might need. (Yes I know it sounds complicated.....! ) Even if I feel even more lazy, I could setup the github webhooks to call the server where I have my personal hosting so that even all the building process I am describing would be automatic on my server... Of course this last step would rely on me too much, so I would say that unlike other projects where documentation might be increasing and improving constantly, Spyder will require periodic updates only, which can be handled manually when needed, if needed. > You also mention Sphinx, and that might be a solid alternative: > * website + documentation in one place > * properly documented (Matplotlib, IPython, Scipy, Numpy are using it) > * I like the simplicity of the Numpy/Scipy sites, but I agree they are not > as fancy as the Rstudio site. However, I find simplicity and > maintainability more important than a fancy design. > Sphinx is definitely a great tool, but it is not as easy to get going as Pelican allows for in terms of the look of the website. For docs great, for website... it does not offer the level of customization I would like for our site. The two projects (pelican and sphinx) use Jinja as a templating system so in theory a single theme could be used for both engines and is what I want to give a try (t least as a proof of concept). If I succeed (fingers crossed!) we will have an amazing looking website (ok... a pretty website) based on up to date css frameworks, mobile friendly and completely coherent and self contained. A problem, or better said, a challenge with Web technologies is that they evolve too quickly... quicker than any maintainer would like to. I personally do not like those websites (numpy and the like), too simple, too old fashioned... and they constrain you to some predefined idea of the structure... it might have been the best tool for those projects, but I think we need to improve on all aspects, look, ease of use and maintainability and bring this project up to date. Pelican is of course not a panacea, but whenever I felt that I was being constrained there was some solution that was built in. Ok back to work... :) > Best regards, > David > ) > > > > On 29 December 2014 at 21:30, Gonzalo A. PEÑA CASTELLANOS < > [email protected] <javascript:>> wrote: > >> Nowadays everyone is using Readthedocs for the documentation, which is a >> really great service, but I do not like that you have to go to another >> place to read the documentation of a project... but then this is just me. >> Read the docs can work great by using the github webhooks and tags so that >> the different versions of the documentation are taken into account. >> >> That was the motivation of my previous question. If we will only maintain >> a single 'latest' documentation, then I could make a template for sphinx >> that would then be "processed" by pelican so they could use the same theme, >> look and site. >> >> This last option would be more work, but would make the site look >> "beautiful" and consistent... or we could just go with the current hype at >> readthedocs.... >> >> Any comments on this issue? >> >> -- >> You received this message because you are subscribed to the Google Groups >> "spyder" group. >> To unsubscribe from this group and stop receiving emails from it, send an >> email to [email protected] <javascript:>. >> To post to this group, send email to [email protected] >> <javascript:>. >> Visit this group at http://groups.google.com/group/spyderlib. >> For more options, visit https://groups.google.com/d/optout. >> > > -- You received this message because you are subscribed to the Google Groups "spyder" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/spyderlib. For more options, visit https://groups.google.com/d/optout.
