Making a kit from an existing package #93
Conversation
|
@ianmkenney let me know when you want me to review this |
There was a problem hiding this comment.
I like the idea of coming at the problem of creating a registered MDAKit from a more generic angle and giving hints about licenses etc. I am missing some concrete examples, though. We don't need a tutorial with a fixed case study. But some semi-generic lines of code that we typically see in the registry. Have a look at what we currently have in the meta.yamls and perhaps an obvious pattern emerges.
Ultimately, I think this section should prepare a developer to fill in the metadata.yml file (see https://mdakits.mdanalysis.org/add.html#template-metadata-yaml-file ); look at the comments in the file on the page as they are currently our primary documentation ( :-( ). If you could expand on what's there then that would be really helpful. If you have some examples for what's expected (or worked elsewhere) then that would also show devs what to shoot for.
* Pre-existing package
ianmkenney
force-pushed
the
makingakit_existing
branch
from
06d4767
to
0f99bc8
Compare
There was a problem hiding this comment.
Thanks @ianmkenney , looking good.
I have some minor suggestions and a broader question, but nothing that would actually block this PR.
|
|
||
| Registering an existing package as an MDAKit is a straightforward process. | ||
| Since the structure of an MDAKit is not as strict as the code found in the MDAnalysis core library, chances are very little restructuring is needed for registration. | ||
| The primary concern is ensuring that the core MDAKit :ref:`requirements<requirements>` are met, as listed at the top of this document. |
There was a problem hiding this comment.
This ref works; just IIRC the sphinx docs say somewhere "space between text and link name", i.e., :ref: requirements <requirements>. Come to think, if title and link name are the same, then just
:ref:`requirements`should work. (But test!)
orbeckst
changed the title
There was a problem hiding this comment.
Thanks for this @ianmkenney, looks great!
I've left a couple of comments for some changes, with one of them being a blocker (@orbeckst's suggestion to switch to git clone latest).
| Although this is the minimum, we highly recommend that you consider generating your documentation with dedicated tools such as `Sphinx <https://www.sphinx-doc.org/en/master/>`_, which allows you to generate static documentation using `reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_ formatted plain-text directly from your code. | ||
| This makes it easier for your documentation to change alongside code changes. | ||
|
|
||
| Using a documentation hosting service such as `Read the Docs <https://readthedocs.org>`_ or `GitHub Pages <https://pages.github.com/>`_ makes public access to your generated documentation automatic. |
There was a problem hiding this comment.
@fiona-naughton these sections might be good entry points for further guides, i.e. this can eventually be switched to "see our guide on building docs for mdakits here".
Adding documentation for creating an MDAKit from an existing package.