tskit-dev/tskit-site

tskit website

tskit.dev

This repo is the source code for http://tskit.dev

The site is made with jekyll and built with grunt.

Dependencies

gem install --user-install bundler jekyll
bundle install 

Building the site

To build the site you will need a github auth token (for API requests, no permissions are needed on the token) GITHUB_TOKEN=YOUR_TOKEN_HERE grunt dev

Data sources

News, software and resources are the jekyll collections driving the site. The front matter of each file in their respective directories provides the metadata for each entry, which is supplemented with information from API requests by plugins. Any information in front matter overrides that from API requests - useful for fixing bad publication info for instance. To not hit rate limiters API requests are cached, to clear the cache rm /tmp/open-uri-*.

To add a new item create an additional file in either the _software, _news or _resources directory. Refer to the existing files for the required YAML keys in the front matter. Any images needed should be places in the assets/images folder and referred to with this template: {{ '/assets/images/PATH/TO/file.svg' | relative_url}} this will cause the file to be added to the build.

tskit-site's Issues

Text for "Genetics Research" page.

JupyterLite deployment

It would be helpful for a lot of reasons if we could have our own JupyterLite deployment on tskit-dev. That way we could host live notebooks for educational content.

We have most of the components needed already in pyodide (although waiting on a release), so we could try this out initially with some simulation/tskit fundamentals notebooks. If it works, we can then look at bringing things like tsinfer in.

Here are the docs for JupyterLite deployment

Any thoughts @benjeffery, @hyanwong?

Analytics

It would be helpful to have some analytics so that we can see which pages are being used, can quantify package popularity, etc.

What are our options here @benjeffery?

Make twitter preview cards work

A quick tweak of our meta tags will help the links to tskit.dev look great on twitter.

Use the tool at https://cards-dev.twitter.com/validator to check the result.

Link to GitHub tskit-dev project site

I was looking for a generic link to https://github.com/tskit-dev from the top of the software page, but couldn't find it - only links to each specific repo.

Check how twitter snippets and google results look

Mobile iteration

Several elements are too wide, make the site more mobile friendly

Make blog slimmer

Legacy docs for msprime 0.7.5

msprime 0.7.5 legacy docs would be good to add to the site as that version was used for a significant time and the release after had major API updates. I don't think we need to build docs for every tagged release (although this might be good as a future project) see tskit-dev/msprime#1704 for motivation.

Brief for hired help

We're considering paying for some work to polish the design of https://tskit.dev, so will need a brief:

tskit.dev is the central hub for open-source tree-sequence related software and research.

Goals:

• Give an overview of tree sequences and their uses
• Act as a resource hub, linking or hosting (as appropriate) documentation, code, release notes, tutorials, talks, videos and papers. Make these resources as "discoverable" as possible.
• Encourage new contributors, indicate that development is free and open and active.
• Signpost ways to connect with and get support from the community via issues and discussions.
• Have a design looks professional, solid and readable on desktop and mobile

Current technical implementation:
Jekyll (Ruby) with custom plugins and theme, deployed using github actions to github pages. Not looking to change/rewrite this unless necessary. We'd like changes to be via github PRs. All development of tskit.dev is open and under the MIT license.

Specified improvements we'd like:

• Design is a rough outline and needs polishing, should integrate well with the JupyterBook documentation sites, so that there's a consistent look and feel throughout.
• Make site design responsive so that it works on mobile and desktop.
• All images are placeholders and need replacing.
• Software logos for tskit, msprime and tsdate to be made consistent and a logo to be made for tsinfer.
• SEO pass needed, along with meta tags for things like twitter previews.
• We're mostly happy with how the information is organised, but open to suggestions of improvement.

Define site colours using css variables

It would be nice to automatically be able to colour SVG diagrams using the site colours. This is a bit tricky because the SVG files contain their own stylesheets, which are not accessible to sass processing.

However, we can use css variables to do this. So in the main stylesheet we would say something like:

:root {
    --main-colour:#06c;
}

(where we substitute #06c with whatever sass colour we want).

Then in the SVG (e.g. of a tree sequence) I can simply do:

<style>.axis line {stroke: var(--main-colour)}</style>

I can't see any down sides to this, as it doesn't affect anything else. The only issue is if it isn't supported in modern browsers (see https://caniuse.com/css-variables). And what names we should use for the site colours.

add pyslim

Add pyslim to the tools powered by tree sequences.

tskit build broken

Needs an update to fix C deps on compiling the python modulel

Add msprime and unified genealogy paper.

Add 0.5.0 blog post

add gspace?

GSpace is a discrete-time coalescent simulator designed for fast simulation on 1D and 2D grids of populations. It can now output tree sequences, and we should list it on the site somewhere!

Deploy tskit/tutorials here

We'd like to deploy the HTML for https://github.com/tskit-dev/tutorials here at the stable URL tskit.dev/tutorials

As a way of avoiding rebuilding the docs locally (and the complexity that does with it) perhaps we could pull in the gh-pages branch? This would be quick and simple, and be a reasonable thing to run on a cron job. Could do the same thing for the msprime docs?

Msprime docs not running jupyter cells

E.g, here we should have some results.

Probably because of the paths or something, because we're rebuilding here? The msprime module needs to be in the PYTHONPATH.

JS for filtering resources

Style for blog page

Needs to work with the notebook output we use for release notebooks.

Link to msprime stable docs when avaliable

Order resources by date

tskit docs build broken

Looks like some issue with the cache @benjeffery?

SVG images?

Should I display TS images on the website using SVG, or use some bitmap format instead?

https://caniuse.com/?search=svg

Suggests SVG support in 99.15% of internet users.

Builds not getting triggered by docs repos

Events on the msprime repo don't seem to be triggering builds here - I've had to manually trigger builds to update the msprime docs.

Possible the same for tskit?

Add favicon

tskit version not rendering

We're seeing tskit __TSKIT_VERSION__ in the jupyterbook code. Probably a very simple fix, mimicing the mpsrime setup

Summarise publications

Now that the learn page is more of a summary we should make the publications list more of a summary.

Msprime doc build failing

SLiM snippet

@bhaller suggests:

initialize() {
	initializeMutationRate(1e-7);
	initializeMutationType(“m1”, 0.5, “f”, 0.0);
	initializeGenomicElementType(“g1”, m1, 1.0);
	initializeGenomicElement(g1, 0, 99999);
	initializeRecombinationRate(1e-8);
}
1 { sim.addSubpop(“p1", 500); }
2000 late() { sim.outputFixedMutations(); }

Make a tskit favicon

I guess that would be nice for the tskit.dev site? Maybe just a 3-tip tree in the logo colours.

Get "help wanted" issues from github api and show on contributors page

We would need to check we had ones that made sense.

Make stable URL for msprime docs locally

It would be nice if the documentation for msprime could live here at a long-term stable URL, like http://tskit.dev/msprime/docs

Initially we could do a HTTP redirect to https://tskit-dev.github.io/msprime-docs/

Nice picture to illustrate a tree sequence on the front page

High-level overview of tree-sequences, with some helpful graphics/animations.

Video clicking doesn't work

Add manual contributor override to config

We need to recognise contributors that are not in the committers list for each repo. This can be done via a hash in config.

Wrong version displayed for msprime

The wrong version of msprime is being displayed on the intro page. For some reason, we've got version = "0.1.dev1", which means that either the custom sphinx extension defined in tskit-dev/msprime#1408 isn't being executed, or the sphinx config is somehow being overwritten later in the process.

The Python path must be OK, because we wouldn't get the autodocs output otherwise.

Any ideas @benjeffery?

make tutorials obvious

Right now it's only easy to tell that the tutorials introduce you to what a tree sequence is, not actually give you examples of how to do other stuff. They're great, we should make them more discoverable.

Wobbly text across site

• Missing background one some pages. Here it is on the photoshops
  

• Need twitter icon and styling for community page twitter link

• Fonts look "wobbly"
  

• icons for twitter, website, rust, r

Add homepage option to software

As suggested by @bhaller, as https://messerlab.org/slim/ is a natural homepage for SLiM. Change SLiMs doc link to http://benhaller.com/slim/SLiM_Manual.pdf

Show version number instead of release text for software

On the software pages, I think it would be more useful to show the release version rather than the label text, i.e., we'd have

Latest version: 1.0.0b3 1 week ...

for msprime. The release names aren't terribly helpful a lot of the time.

Add Relate / Collate to the software->infer section?

Should we do this? The RelateFileFormats program has a --mode ConvertToTreeSequence, but it makes a JBOT and loses information. Still, other people might want to use Relate for some things?

Msprime version not shown correctly in "stable" branch

In the msprime stable brach we're seeing msprime version __MSPRIME_VERSION__ rather than the replaced version.

Dead link checker

Possibly as part of CI for PRs, howver I don't think the build and deploy should fail due to this.

Add dev guide

Use release versions of msprime and pyslim

We're currently hacking around compatibility issues on CI.

"latest" docs give "tskit __TSKIT_VERSION__" as the version.

Should we tweak something in the CI build chain so that the left hand sidebar in https://tskit.dev/tskit/docs/latest/ gives a number like "tskit 0.3.8.dev1" rather than "tskit TSKIT_VERSION" (i.e. make the CI build do make dist)? We could presumably match the msprime process, which currently gives msprime 1.0.3.dev93 for the "latest" docs.

Retire venv caches?

The various caches on the msprime build seems to break pretty regularly - are they worth it? The sha1 cache works really well, in that we skip builds on stuff that's not needed. I'm not sure avoiding the pypi downloads are worth it though.

adjust SLiM version after pyslim release

See TODO note in 48693dd

Add blog/announcments/... section

@hyanwong and I have been discussing the idea of having a "blog" in which we can have pages to do quick examples. For example, it would be great to do a "What's new in tskit 0.4.0" post based on @benjeffery's notebook from a few weeks ago. After some discussion, we think it's probably best to not be dynamic, so that the content stays the same over time.

Nothing fancy required really, just markdown input, and the ability to convert Jupyter notebooks into something that looks OK in the final version.

Any thoughts?