I’m happy to announce a brand new https://pkg.julialang.org site. You can search for packages by name and topic (topics are populated from GitHub) and view the docs for all registered packages in one central place. In the near future it will also have full documentation of all packages and regex code search.
We hope that this service will not only help Julia users discover great packages more easily, but also make it a little simpler to develop and publish those packages. It removes the burden from package developers of figuring out how to host docs and provide search functionality. The service is based on DocumentationGenerator.jl and has been the result of the efforts of many people, including @pfitzseb, @Venkatesh_D (both at Julia Computing) and @sdanisch (at NextJournal). Major thanks to all who have contributed!
The package doc & search service is part of the JuliaTeam Vision and is one of the services that Julia Computing is developing, hosting and maintaining to support the open source ecosystem. The service is also available as part of the JuliaTeam product for organizations that want to have centralized package doc & search for their private Julia packages.
I am curious how tags work? What are the steps that package authors should follow to have their packages listed under the “statistics” tag for example?
The link for the DiffEq docs seem to be broken, pointing to some alternative site? I am curious if there is something we need to set for this to know where the docs are at.
As a side question, please let me know if there is a better way of building documentation in Julia packages. I like the Travis job approach because AFAIK it is performed in parallel.
How does this work, ie what should the package authors do for this to work? Just have the docs in docs? Does this mean that we don’t need to generate and deploy docs any more?
Also, DynamicHMC.jl is not showing up for some reason, while my other packages are there.
It seems that the documentation link defaults to something built from the package readme. This sounds like a good fallback, but in many cases the package has a native documentation that perhaps would be better to link to. I noticed that the native documentation is indeed linked in some cases, but not all. Can one edit this link manually somehow?
The website seems excellent! I am very happy that one can search by tags, this makes perfect sense and seems to work! Hopefully this will make finding Julia packages easier for new users. We now all have to take good care to choose proper and plentyful github tags to help everyone!
I also appreciate the attempt at “automatic generation” of documentation, but it may backfire… Most packages built their own docs which has nothing to do with the README file. Wouldn’t it better to just link the documentation page instead of automatically generating something? README files have a “docs” badge, you can use this to automate the process.
For example, Finding DynamicalSystems.jl and clicking documentation just shows a rendering of the README and then has a long list of failed docstrings. This just gives the impression of non-professional documentation. I’d certainly like to avoid this given the absurd amount of time I’ve spent making the true documentation as professional as possible.
By default, we build whatever you have in docs/make.jl or fall back to your README, but you can also
give us a repo/branch where we can find your docs so we can build those, or
give us an URL with the built docs we can link to.
I think those options should cover every eventuality, but let me know if not.
This is another reason we need the above implemented – many big packages/orgs (DiffEq, Juno, etc.pp.) have their docs set up in a different repo which we can’t find right now.
Unless you have special requirements (e.g. you need a special travis setup or whatever) then that should be enough, yes.
That’s a fair point. The options outlined above should address it though, I think. Maybe we should also make it more obvious when the docs are autogenerated.
Thanks Seb, this sounds fair and square and indeed should cover everything. Please share with us where we can submit this doc link corresponding to point 3. (when it is ready)
If people could please file issues at GitHub - JuliaDocs/DocumentationGenerator.jl that would be super helpful. We’ll be paying attention to the repo, responding there and fixing issues as they come up.
It would be nice if the “Explore Packages” link in julialang.org linked to pkg.julialang.org. I apologize if this appears unappreciative to the JuliaObserver devs (the current destination of that link), but I didn’t get the impression there were particularly serious intentions to maintain that (correct me if I’m wrong).
