Move in place three sections to docs "How-to" (in Managing your installation) #4074
Conversation
|
The only question I have is the folder Suggestions for a different name (or different location) are welcome. |
There was a problem hiding this comment.
I made some general suggestions on how to improve the style and maybe make the content a bit more concise.
For some of the content, especially the backup section with O/S specific instructions, I make suggestions on how to either move or place it such that it does not impede the general flow and is better separated from content that is more generally applicable. I think we should aim at streamlining these sections such that they remain clearly problem-oriented. See my specific comments for details.
I also suggest to introduce a new top-level how-to section on "how to run on clusters". While very relevant for users that do run on clusters, I think it is obstructive for those that don't, so a better separation is probably desirable. It will also help cluster users find the related content more easily.
|
Thanks @csadorf, I'll apply the rest of the comments (mostly involving moving stuff around) tomorrow. Sorry also for the many commits, I didn't get at the beginning how to batch suggestions together (was working from the discussion pane and not from the files pane). |
giovannipizzi
changed the title
There was a problem hiding this comment.
thanks a lot @giovannipizzi
I added two comments I had written down for myself to fix at some point.
They are easy to address.
giovannipizzi
force-pushed
the
fix_4001_docs_manage_installation
branch
from
88c17ac to
b55373d
Compare
|
@giovannipizzi Is this ready for another round of review? |
giovannipizzi
force-pushed
the
fix_4001_docs_manage_installation
branch
from
b55373d to
addd83c
Compare
|
Hi! |
|
@csadorf FYI I'm going to add a new short section that was just contributed by Nicola Spallanzani, as it fits in here; I'm also going to rebase so you can check on CircleCI |
giovannipizzi
force-pushed
the
fix_4001_docs_manage_installation
branch
from
c0a2c6e to
414fa83
Compare
|
@csadorf OK, done! |
giovannipizzi
force-pushed
the
fix_4001_docs_manage_installation
branch
from
395802f to
2709757
Compare
…ections: how-to:tune performance (fixes aiidateam#4002) how-to:update installation (fixes aiidateam#4003) how-to:backup (fixes aiidateam#4004) I'm doing these in a single commit since they are closely related (especially for what concerns links)
Some reorganisation of content and some rewording Co-authored-by: Carl Simon Adorf <carl.simon.adorf@gmail.com>
Co-authored-by: Nicola Spallanzani <nicola.spallanzani@max-centre.eu>
Co-authored-by: Carl Simon Adorf <carl.simon.adorf@gmail.com>
giovannipizzi
force-pushed
the
fix_4001_docs_manage_installation
branch
from
2709757 to
ccf2487
Compare
|
@csadorf comments addressed (or commented/replied above) - this is now ready for re-review |
| - `Additional instructions on how to migrate from 0.12.x versions <https://aiida.readthedocs.io/projects/aiida-core/en/v1.2.1/install/updating_installation.html#updating-from-0-12-to-1>`_. | ||
| - `Additional instructions on how to migrate from versions 0.4 -- 0.11 <https://aiida.readthedocs.io/projects/aiida-core/en/v1.2.1/install/updating_installation.html#older-versions>`_. | ||
| - For a list of breaking changes between the 0.x and the 1.x series of AiiDA, check `this page <https://aiida.readthedocs.io/projects/aiida-core/en/v1.2.1/install/updating_installation.html#breaking-changes-from-0-12-to-1>`_. |
There was a problem hiding this comment.
The other approach to this is to keep move these sections to e.g. docs/source/howto/_version_migrations.rst and link to that.
Then at the top of that document put :orphan:; this tells sphinx that the document is not required to show up in any ToC. This is what I have currently done in #4060 (see https://7-77234579-gh.circle-artifacts.com/0/html/intro/installation.html#updating-aiida-core), but I will remove that section and link here
Add how-to sections for: how-to:tune performance (fixes #4002) how-to:update installation (fixes #4003) how-to:backup (fixes #4004) how-to:installation:running-on-supercomputers Co-authored-by: Carl Simon Adorf <carl.simon.adorf@gmail.com> Co-authored-by: Nicola Spallanzani <nicola.spallanzani@max-centre.eu>
In particular, moving:
how-to:tune performance (fixes #4002)
how-to:update installation (fixes #4003)
how-to:backup (fixes #4004)
I'm doing these in a single commit since they are closely related (especially for what concerns links)