Revamp the website

[cdiener]

As discussed there should be a revamp of the website soon in order to promote cobrapy and packages that use it. The following features were recommended/requested:

• better info about the project (maybe migrate the new description and guides)
• list of packages using cobrapy
• tags for packages to sort by functionality
• list of publications using cobrapy
• logo?

I'll have some time in vacations and wanted to play around with some web stuff anyways, so I could do a mockup that can be discussed here. Let me me know what you think...

[cdiener]

Post your logo ideas here. Here is one that does not involve a snake...

[hredestig]

It would be great if you could do that! github stars were discussed here, perhaps one can make them display next to project on the webpage using their api.

[pstjohn]

I've done a few github pages in jekyll before, so I'm also happy to help.

[pstjohn]

On the logo, I think it looks awesome! My only comment is that it's not clear its for biology/metabolism (could be something like networkx, for instance).

Here's a suggestion for a larger splash-page logo (I'm biased coming from microbial modeling 😄 ). You'd keep the smaller one for places that it makes more sense.

[cdiener]

I agree. The network meabt to be reminiscent of the TCA cycle but I failed with that :/ I like the idea of the E. Coli. I also have a small flux cone. Maybe we can put some pictograms below. I'll make a mock-up tomorrow.

Regarding the page, help will be appreciated. To be honest I planned to use Hugo since it's like Jekyll just much faster and a single binary...

[phantomas1234]

We should stick to Jekyll because then we can rely on github for all the rendering.

[phantomas1234]

I saw that you used material design for your personal website @cdiener https://cdiener.com/ (did you use one of the static frameworks like http://materializecss.com/?). We also use material design for most of the things that we do nowadays so I'd prefer to use it for the opencobra/cobrapy website. https://github.com/dd-decaf/website (something we put together for a project) would be a good starting point I think for a md site based on jekyll.

[pstjohn]

I've used bootstrap before, which is fairly easy to pick up. Never seen materializecss, looks neat though!

[cdiener]

Jekyll on Github is pretty limited in terms of plugins. For instance there is no good solution for tags. This is why I would prefer Hugo. Rendering is a 40 ms step before push and it allows people to check the end product before making the PR. Also Github pages rendering breaks a lot.

I use Material Design Lite from Google (https://getmdl.io) because it's relatively small and the only one that gets feedback from the Material Design committee...

[pstjohn]

works for me

[cdiener]

Maybe coming back to the generator. Looks like most of you use Jekyll and if we don't use tags on the website I would agree with that and not impose. I think the biggest point of discussion will be the actual look (what looks "good" is pretty subjective), so my idea was to build something simple that we can discuss. Converting the final product to jekyll, hugo or hexo should not be too complicated after we agreed on the design itself...

[cdiener]

@pstjohn here is a version that uses your idea and better specifies for what you can use cobrapy (or cobra? never really discussed it...)

[pstjohn]

Honestly I'm not even sure we'll have much markdown, so it could be a moot point. We're not running a blog where we're going to changing the pages much.

I would guess you'd have an intro page with the logo and links to github + readthedocs, maybe Installation: pip install cobra and 'citing cobra': bibtex with citation info.

Then a couple of other pages with a sidebar nav,

• "projects" (I wonder if this could just be a csv file that gets parsed appropriately with some sort of javascript plugin or liquid template. You'd probably need javascript to have the dynamic filtering by tag)
• "publications", probably a big bibtex file and some citeproc-js scripts
• "contributors", some brief bios?
• "getting involved", probably a link to the gitter, contributing.rst, and the issue board.

[cdiener]

It would be easier to just have markdown pages for each project, pub and write list pages for them. This way PRs just add some new small files. If we parse it from JSON, YAML, CSV you have to write pagination yourself since jekyll and friends only have that implemented for the normal markdown pages. Also if any of those get big you are generating lots of content with JS everytime the page is loaded which defeats the point of static pages. Hugo can load JSON, YAML and TOML on page generation and use them in templates, so that could be an option. Generating JSON/bibtex etc output for the list views would be easy though. My idea for sections was:

• Intro (general info)
• Projects/Packages
  • all of them (maybe 20 per page)
  • tags (filter)
• Publications
  • all of them (maybe 10 per page)
  • tags (filter)
• Contributing (explain how to help with cobrapy and the page)

So pretty much the same you just said.

[pstjohn]

Do we want separate pages for each publication / projects? What would be on them?

[cdiener]

Nothing, you only implement the list view similar to all those blogs that have several complete articles per page (only that they are a bit shorter in our case).

[pstjohn]

oh neat. yeah that works then

[cdiener]

But you are completely right. That actually creates some empty 0 byte files for the non-existing single posts. Parsing from JSON or something would be an alternative. Hugo seems to allow applying Pagination onto data objects but I did not find how to do that with jekyll.

[phantomas1234]

All of this sounds good to me. Hugo looks nice but its speed benefit doesn't really apply in this case I guess. Since it looks like we're not going to rely on GitHub to build the site (so we need to compile it ourselves and push it with every change?), would maybe sphinx be an option too (like we did for cameo.bio)? This way we would have all the information in one place? Could build the sphinx docs+website on travis-ci and push to gh-pages branch whenever something changes in the docs/site? With a few exceptions though, most sphinx themes look ugly as hell. https://getmdl.io/ is fine with me because materializecss had some issues.

[cdiener]

I preferred hugo more for the ability to automatically create tags and pagination which is necessary since we are basically managing two large lists of items: publications and projects/packages. If sphinx knows how to do that it would be an option if not it would again mean to implement features that are already stably implemented in other tools. In this case combining sphinx and hugo could be an option (the difference to only using sphinx would be 5 MB download). I don't really use sphinx so if somebody knows how to write a template it would help :)

EDIT: attached the inkscape SVG in case you want to modify it.

[phantomas1234]

If anyone would draw it nicely, would you consider this variation of the official python logo to be an option 😏?

[cdiener]

@phantomas1234 I think we have to ask the PSF to be allowed to modify the logo... I also started trying to draw snakes but it turned out to be difficult :) Others have made a far better job

[cdiener]

Preview can be found at https://cdiener.github.io/cobrapy_website/. Will probably change the following days.

[pstjohn]

Looks fantastic!

Some minor thoughts:

• the logo takes up a lot of real estate when you have a wide browser window open.
• I'd say 'community supported' somewhere in what is cobrapy
• Delete the 'More information about opencobra is available at the website.' line in 'Getting Help' :), it'll just be a self-link.

Also, it would be great if we could do a few code snippets, just to show off some of the most commonly used tools. Maybe just loading the e coli core model from SBML, optimizing, and showing a couple summary calls (one with FVA?). Maybe booting up something in cobra.flux_analysis and then having a quick list of supported methods.

[cdiener]

Thanks @pstjohn! The logo currently has a max-width of 800px. What would you consider a good number here (you can play around by pressing F12 when on the page and changing the value in the developer tools - styles tab)? I just copied some text fragments from the README :sweat_smile:. The things you mentioned definitely need to be changed.

I like the idea with the code snippets. Maybe we call it "Getting started"... Where should that go? Above/below installation?

[pstjohn]

On the logo, I think a max width of around 500px is probably reasonable. Even that might be a bit much.. I just think it would be cool if we had a bit of some code snippets in view when you first load the page so the viewer knows to scroll down to see more. It currently looks like a full screen logo that sortof invites you to click on those buttons (models, fluxes,…) which don’t actually do anything (nor am I saying they should).

Idk, just suggestions. I'll try cloning the site and playing around with hugo a bit to do some code snippets.

I'm really just thinking something like how jinja does the snippets, if I find more examples I'll post them here too

[cdiener]

Changes from @pstjohn are now merged. Now would be a good time to think about deployments. Options are:

1. Source and generated page resides in the github_pages branch. Site is generated manually on source changes.
2. Source resides in github_pages branch. Site is generated with the normal cobrapy CI and pushed with a service account.
3. Source resides in an external repo. Page is generated into cobrapy:github_pages manually, automatically with Travis CI with a token or cerates a PR using the github API.

[pstjohn]

So, just to make sure I understand this, when you run hugo server, it currently constantly rebuilds the static site in /docs? And then the github.io API will serve the static website from the docs/ folder in the master branch?

A 4th option could be to follow escher's example, and host the website at cobrapy.github.io. The problem there would be that there's already a user named @cobrapy. Does that account belong to anyone here? Could we still create a separate cobrapy organization to host a 'cobrapy.github.io' website?

[cdiener]

No, hugo server builds the site in RAM and serves it (that's why it is fast). It writes nothing to the disk.

Just hugo builds the site into a public folder in your current directory. That folder can be changed with the -d option. For instance hugo -d docs builds into the docs folder as currently done for the website mockup.

[cdiener]

A travis CI example can be found here.

[pstjohn]

interesting.. cool setup!

If we're planning to keep the docs hosted as they currently are, then I don't think the website needs to live in the cobrapy repo. If we had a link in the readme, that would likely be enough.

[cdiener]

If the username is ours that would be cool. @phantomas1234 had the idea to include the sphinx docs in the webpage, but that would require writing a sphinx template...

[CobraPy]

Hi I'm cobrapy- cool project. Should I give you my username so you can take over? I don't use it that much anyway. Do I just change it to something else?

[cdiener]

Website has been merged for now. Closing in favour of regular updates.

[pstjohn]

Let us know what you think is the best way to open up the website for regular updates. Maybe the simplest would be cobrapy-website repo in the opencobra organization?

[cdiener]

I think that would be a good option. We could set up automatic pushes to the cobrapy:gh-pages branch from there. There is an example here but it requires a Github token...

[pstjohn]

Do you need extra permissions to move cdiener/cobrapy_website to the opencobra organization? What are the implications of the github token?

[cdiener]

No, I will move it in a second.

A github token gives write access to all repos the owner has write access as well. So there is a security risk if the token gets compromised. However, tokens can also be revoked at any point....

[cdiener]

Correction, I do not have the permission to create repos on opencobra so I can't move it.

[pstjohn]

So we'd probably make a cobrapy website bot account? gh-pages isn't a protected branch, so it would only need the collaborator-level access to the main cobrapy repo.

@opencobra/cobrapy-admin, do you think someone could create the cobrapy-website repo on opencobra?

[phantomas1234]

@cdiener @pstjohn I created https://github.com/opencobra/cobrapy-website/.

[phantomas1234]

I am a little bit confused about the workflow? So the cobrapy website source will be kept in opencobra/cobrapy-website and on commits, travis-ci will use hugo to compile the static HTML and push it to the gh-pages branch on opencobra/cobrapy?

[cdiener]

You don't look confused to me because that was spot on :)