New docs

[manulera]

Hello @BjornFJohansson @hiyama341 @dgruano @JeffXiePL

I have made some changes to the documentation that I think can make it a bit more engaging and easier to maintain.

Because the action is set to deploy from any branch, it has actually updated the docs to that, but as soon as someone pushes again, it will be overwritten, so you can check it in this netlify link: https://keen-jalebi-634077.netlify.app/

The main changes I have made:

• Separate it into several sections, so that it's not a single long page with the module documentation (that's still there, but it's now just one of the sections).

• I have added a script that is run when the docs are created in a github action, that converts the notebooks to markdown files, so they are included in the documentation as well.

  • That allows to search for the text in the notebooks, which is great to find solutions quickly.
  • For now, I have included two of them (one for getting started, one for examples), but I will add all of them if you think it's a good idea. I will also document how to add a notebook so that it's included in the documentation.

• I have added a custom css file that is used to style the notebooks and make the output cells that are too long scrollable, so that it's easier to read.

• Some of the content that goes into the docs pages is directly taken from the README.md file, so there is no need to repeat the docs in two places. I think this is so much better for maintenance. It's very simple with sphinx, you can check the file installation.rst and see that it's really simple to do so:

  .. include:: ../README.md
  :parser: myst_parser.sphinx_
  :start-after: ## Installation 📦
  :end-before: ## Contributing and feedback 🛠️

  In the long term, we should use comments instead to mark the start and end of what goes to the docs, but for the example, I just did it like this.

Let me know what you think. If you agree, I will finish up the changes and add the documentation of how to add notebooks to the docs.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 93.68%. Comparing base (fd8577c) to head (72c13aa).
Report is 5 commits behind head on dev_bjorn.

Additional details and impacted files

@@              Coverage Diff              @@
##           dev_bjorn     #304      +/-   ##
=============================================
+ Coverage      93.60%   93.68%   +0.08%     
=============================================
  Files             40       40              
  Lines           3922     3960      +38     
  Branches         588      604      +16     
=============================================
+ Hits            3671     3710      +39     
+ Misses           199      198       -1     
  Partials          52       52              

Files with missing lines	Coverage Δ
src/pydna/crispr.py	87.23% <ø> (ø)

... and 2 files with indirect coverage changes

[BjornFJohansson]

I looked at the docs in the link and I think they look good. Some of the symbols do not work, like ☢️ on the first page. I think it needs an attractive image on the first page as well.

All the pages under "module content" seem the same? Should each module have its own page?

[manulera]

Some of the symbols do not work, like ☢️ on the first page

Yes, this is because they are using the :emoji_name: syntax, which is not rendered in rst, they simply have to be replaced by the actual emoji, but I did not want to edit the README in this branch, since the other branches do.

needs an attractive image

What would you put?

All the pages under "module content" seem the same?

What do you mean? Now "module content" roughly corresponds to what the previous documentation was ( the autogenerated docs) is there something repeated?

[BjornFJohansson]

It seems like every page under the links in the gray area is a a different part of the same page.

In the Biopython docs it seems like
there is a file for each module.

The way it works in Pydna is perhaps due to old sphinx settings?

[manulera]

Yes, they are all in the same page as before. This is defined in module_contents.rst, we could make it so that every submodule is in a different page if you think it's better.

[manulera]

Anyway, let me know about the sub-pages for the modules, and if you agree with the overall idea. If so, I will add the rest of the notebooks and document how the docs generation works.

[BjornFJohansson]

I do agree with the overall idea. I think it would be better wit ha page for each module as we hope to expand the docstrings for most modules. It is not urgent imho.

[manulera]

Ok, I think it's looking good by now, and I incorporated what you suggested. You can have a look at how it looks in the same URL: https://keen-jalebi-634077.netlify.app/

I have documented how to work on the docs, and referenced it in the readme, so you can easily contribute:

https://github.com/BjornFJohansson/pydna/blob/fa07e0eee05188e5f535a33d902e78326fea4be7/docs/README.md

[dgruano]

Now that we are at it and related to #259 : the Cas objects describe the structure of the sgRNA in the docstring. This causes some artifacts in the documentation page. I attach images of how it looks in the editor vs in the docs:

Any idea on how to solve/workaround this?

[dgruano]

Okay, quick Google search explains how to create code blocks within Sphinx: just adding double colons before the text "::" (unless you can suggest something else).

We can take care of this with @JeffXiePL when we push the changes on the CRISPR module and its docs.

[manulera]

Hi @dgruano good catch! Thanks for checking. I fix it by adding a codeblock and with indentation, see:

72c13aa

[manulera]

Ok, I will merge this then, and we can always improve further.