New pkg.julialang.org

I have the tag statistics in GeoStats.jl for example but it doesn’t show up. Appreciate your advise.

The GeoStats package doesn’t seem to show up at all. Perhaps the doc build failed?

I checked the docs for Gadfly and a lot of plots don’t show e.g. the plots that use RDatasets. RDatasets is not a Gadfly requirement, but it is a requirement for building the docs.

I am building the docs on a separate process on Travis, would that be an issue? https://github.com/juliohm/GeoStats.jl/blob/master/.travis.yml#L17-L26

Possibly. Anything non-standard might cause problems. Will look into it.

1 Like

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.

2 Likes

https://github.com/thofma/Hecke.jl is not showing up. I am building the docs similar to @juliohm in the “new way” as described in PSA: Use a project for building your docs.

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?

3 Likes

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.

5 Likes

So the longer term plan here is to allow you to specify what you want us to do:

  1. By default, we build whatever you have in docs/make.jl or fall back to your README, but you can also
  2. give us a repo/branch where we can find your docs so we can build those, or
  3. 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.

10 Likes

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)

1 Like

It is available now

If people could please file issues at https://github.com/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.

3 Likes

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).

1 Like

I will add pkg.julialang.org in addition to JuliaObserver. In fact when the julialang.org website went live originally, we had links to both.

2 Likes

Thanks for this!

Just picked a corner case: a package like Pkg.jl doesn’t show up in the search results.

2 Likes

Pkg is not registered in General. When more standard libraries get their own repos like Pkg it would be nice with a dedicated section for those on pkg.julialang.org. For the time beeing it could be worthwile to special case Pkg to include it.

1 Like

It would be great if there was some way of coordinating the redundant tags, for example there is a math and a mathematics tag… maybe the result lists could be combined for words like that.

All it would take is a list of synomyms, so that equivalent words and tags get grouped. (#16)

1 Like

Once search works, we’ll probably also want to inlcude Julia’s own docs since that badly needs search that works. We can probably have options to search any of:

  • base
  • stdlibs
  • packages
8 Likes