Streamline README

[manulera]

I think it would be good to streamline the README.

• For docs: refer to notebooks with good examples
• A lot could be moved to a separate "Contributing notebook"

[BjornFJohansson]

Good Idea. I wonder if we could model the pydna README using a good example? Here is a list of supposedly good readmes.

What is good/bad in its current form?

[manulera]

Hi @BjornFJohansson some ideas of what to change:

• I would remove the Usage section entirely, or replace it with a shorter example in code, not an image so that it can be copy-pasted with trying. I think it's probably better to refer people to a documentation page.
• Who is using pydna -> move to the bottom
• Installation -> streamline and remove "generic python / pip usage" content.
• Source code -> remove
• Minimal installation dependencies -> remove (outdated + same info is in pyproject.toml)
• Requirements for running tests, coverage and profiling -> Remove, since this is all now handled with poetry install and anyway documented in pyproject.toml
• Contributing -> perhaps develop further giving a bit more detail for newcomers
• Building a pypi package -> Do you still do this locally or via an action?

[manulera]

Contributing should include hooks installation and what they do, including those for notebooks, we can simply link to the issue that mentions that.

[manulera]

@BjornFJohansson @hiyama341 You can create codeblocks with highlighted text like this (directly on normal text, not inside a codeblock)

<pre>
aaa<mark>TT</mark>aaa
</pre>

This is how it renders:

aaaTTaaa

[BjornFJohansson]

Should we update the last section "Who is using pydna?"

Enabling AI in synthetic biology through Construction File specification https://pubmed.ncbi.nlm.nih.gov/37956196/

[manulera]

Yes, I can add that, also don't merge yet since there are still some small things to fix.

[manulera]

Enabling AI in synthetic biology through Construction File specification https://pubmed.ncbi.nlm.nih.gov/37956196/

Not sure we should include this article which proposes a text file specification for history that we are not planning to use and seems unmaintained.

[manulera]

Hello @BjornFJohansson @hiyama341 @dgruano. I have worked on the README and I think now it is in good shape.

Because I thought it could be a bit hard for newcomers to setup the poetry environment and it may put them off, I have also included a way to set up the dev environment with "vanilla python" in this section.

The way it works is that I have added a new hook (see .pre-commit-config.yaml) that ensures that a file requirements.txt is kept in sync with the poetry environment. That means that you can re-create the same environment using pip only. The issue is that you cannot update project dependencies without using poetry, but that should be a rare case anyway.

This took a while to set up, so please have a look at the docs and see if you can reproduce or you have some feedback.