A blog is a good way to disseminate updates, examples or particular use-cases. They can be reposted, shared and so on. That’s why many packages (for instance for R) use their GitHub page for hosting a blog, and creating blog posts is easy with tools such as knitr and Rmarkdown.
However, Julia packages usually use their GitHub page for storing their documentation, created with the awesome Documenter.jl package.
I was wondering if it was possible to have both worlds at the same place, by including a blog-like type of section or page within the documentation created by documenter? Would that be feasible?
I don’t think blogs go with the official documentation.
They are supplementary instructional material.
And part of their value is that they are not official, and may be very opinionated about the right way to do things.
We do, therefore, offer you our practical judgements wherever we can.
As you gain experience, you will form your own opinion of how reliable our advice is.
Be assured that it is not perfect!
I see no technical reason why one couldn’t include blog-like content with something made using Documenter.jl.
I just don’t see that it belongs in the docs.
My pet package DataDeps.jl has a very long and detailed readme (that I should probably split up into documentor.jl style docs).
It also has links to a blog post, on my blog that really shows it off.
I am co-maintaining TensorFlow.jl, it has docs.
Even a tutorial or two in those docs.
But totally separately to that, I have at least 3 blog posts on it.
Talking about how to use it for specific problems, combining it with other packages,
or comparing it to other packages.
They are just not the same kind of thing and don’t fit together well.
I am super in favour about blogging about packages, and linking to the blogs.
I just don’t think they are better off being in the manual.
I understand and agree that a blog and a documentation are fundamentally different things (and should remain separate).
It’s just that it would be easier to maintain and develop if both had the same “infrastructure” and both were generated automatically from julia files in the repo…
I guess this is up to the authors of both then — if it is easier, some people will surely pick it. If you care about this, you could make an example repository that showcases the setup.
I am not sure that there is a lot of shared infrastructure though: documentation is usually generated by CI using Documenter.jl, while blog posts are just updated whenever the author has something to say. Perhaps Literate.jl could be better for blog posts that contain code.
If you want sure.
What in particular is stopping you?
Sorry, I may have gotten lost on a rant and missed the core of your question/what you wanted to discuss.
Could you reiterate it for me?
Do you need RSS support added to documentor?
(It is doable to code RSS support as a template, I feel sure you could trick documentor into making it)
Can we generate a blog (with julia code) from julia files (or something related, notebooks or an equivalent of .Rmd files), that would be automatically generated and updated
What are the options for hosting this blog, can it live in the github pages (alongside the documentation, in a different section or on the index page) or are there any other good options for hosting this generated blog
Are there any documentation (or blog posts ) out there to help setup something like that
Sorry for that, no I believe it is theorethically easier to do, and I have some experience with documentation (for python packages) and blogs (for R packages), but don’t know how to do them (and even less combine both) in Julia…
Thanks for the link to Literate, it looks great it might be a very good start indeed
Think of Documenter.jl as a special type of static website generator. It is workable for blogs, but far from ideal, for this I would recommend Hugo or Jekyll.
My Jekyll blog is automatically generated from Jupyter notebooks.
(Well there is a script I have to run each time I change a page, but that could be pushed into a CI server)
Here is the script
But that is useful because I like writing in in notebooks,
better than I like writing in markdown, with fenced code blocks which is what Literate.jl or Documentor.jl wants.
At some point I am going to work out a way to make Documentor eat notebooks, probably using nbconvert, just like like how my blog works.
I also prefer notebooks over blogs. Blogs, I feel, are more rigid and doesn’t allow people to experiment with the code unless they set up the whole base. For my packages, I prefer to include a jupyter notebook in the examples folder (MAB.jl/01_Introduction.ipynb at master · v-i-s-h/MAB.jl · GitHub). A notebook can be written like a blog, yet give the users the freedom to directly experiment. Once they install the package, it’s quite straightforward to start by reading the blog and executing the program together. At, if the user doesn’t want to install anything, even then github does a wonderful job in rendering the notebook beautifully so that it can be read as a blog.
It makes sense indeed. It would be the perfect answer if it was possible to add some form of RSS support so that every new notebook in the example folder would be automatically caught and displaydd by other websites (such as blog aggregators). Altough I guess you could tweet everytime you release a new notebook…
) out there to help setup something like that
Sorry for that, no I believe it is theorethically easier to do, and I have some experience with documentation (for python packages) and blogs (for R packages), but don’t know how to do them (and even less combine both) in Julia…