Splitting the tutorial #173
Conversation
fiona-naughton
added
the
documentation
There was a problem hiding this comment.
This is excellent! It becomes much more digestible and you added a lot of good bridges between existing content.
I found a few typos that need correcting.
I would also prefer About (or similar content) to be more prominent. It's important that people understand quickly what MDAKits are.
If you need another page for "Other resources", perhaps make a separate Citations page. Then it's also clear how to cite.
(Not for this PR: We should change the title of the Registry page itself to simply Registry of MDAKits and not write out "MDAnalysis Toolkits" — explaining this is the job of the landing page/About page. For the registry title we should just use our "brand name".)
| A `video walk-through <https://www.youtube.com/watch?v=viCPUHkgSxg>`_ | ||
| of this tutorial is available on YouTube. |
There was a problem hiding this comment.
Is there a way to embed the video?
There was a problem hiding this comment.
There was a problem hiding this comment.
There was a problem hiding this comment.
Actually, there's an open issue #86 ... so this is not something that needs to be solved in this PR!
There was a problem hiding this comment.
I've had a go at this, anyway (it didn't seem complicated, so might as well kill two birds with one stone)
| *For a video demonstration of this section,* | ||
| `click here <https://www.youtube.com/watch?v=viCPUHkgSxg&t=48s>`_. |
There was a problem hiding this comment.
I would avoid "click here" – see https://www.w3.org/QA/Tips/noClickHere .
Instead make the link say what it is.
| ******************************* | ||
|
|
||
| *For a video demonstration of this section,* | ||
| `click here <https://www.youtube.com/watch?v=viCPUHkgSxg&t=153s>`_. |
| ******************** | ||
|
|
||
| *For a video demonstration of this section,* | ||
| `click here <https://www.youtube.com/watch?v=viCPUHkgSxg&t=72s>`_. |
| ********************************* | ||
|
|
||
| *For a video demonstration of this section,* | ||
| `click here <https://www.youtube.com/watch?v=viCPUHkgSxg&t=247s>`_. |
| :alt: Import a project into RTD | ||
|
|
||
| #. Find the Kit repository and click "+". Confirm that the name, URL, and | ||
| default branch (likely be `main`) are correct. |
docs/source/making-a-kit/hosting.rst
Outdated
| through these services is highly encouraged. | ||
|
|
||
| However, your code **does** need to be installable from source. You'll specify | ||
| the commands for this in the ``scr_install`` field of your ``metadata.yaml`` |
| *For an example, see* :ref:`example-registration` *from the guided | ||
| MDAKit cookiecutter example.* |
docs/source/index.rst
Outdated
| :maxdepth: 1 | ||
| :caption: Other Resources | ||
|
|
||
| about |
There was a problem hiding this comment.
I would leave About near the top of the list and also make sure it's linked from the intro text.
What do you need to see if someone sends you to mdakits.mdanalysis.org for "their code" and you don't really know what to with this? Or "just make a MDAKit out of your code".
docs/source/maintainingakit.rst
Outdated
| ********************* | ||
|
|
||
| .. note:: | ||
| This section is still under construction, and more information will be added |
There was a problem hiding this comment.
I'd remove the ", and more information will be added soon!". Who knows when content will appear...
Perhaps encourage contributions or link to discussions, maybe we get enough discussions/solutions so that we can put it here?
|
Just to add: I'd really like to see your update live soon as it's a massive improvement in readability and it would make it so much easier to send people to specific pages for advice. |
fiona-naughton
force-pushed
the
split-tutorial
branch
from
3e8d85b
to
6230777
Compare
|
Thanks @orbeckst - hopefully I've addressed all your comments! |
|
Looks great!!! |
Addressing #156 , though I may have got a little carried away in tidying up/adding some other stuff in the process.
The Making (and Registering) a Kit page is now split over multiple pages (and further split to numbered steps), and the pages have been slightly re-ordered. The basic tutorial content should be largely intact, but I reworded/added some things I felt would improve clarity and make it flow better now it's over multiple pages, particularly at the start of the adding documentation section, and there's a "requirements checklist" that gets updated at the end of each of the tutorial pages.