-
Notifications
You must be signed in to change notification settings - Fork 187
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Docs revamp #4141
Docs revamp #4141
Conversation
The new skeleton contains the following top level sections * Getting started (into) * Tutorial (tutorial) * How-To Guides (howto) * Topics (topics) * Reference (reference) * Plugins (plugins) * Development (development) The value between parentheses is the name of the directory in which the relevent documents should be placed. Currently these new folders only contain a single `placeholder.rst` index file. From here, we will slowly start to move existing documentation from their old files into the new locations, while correcting and improving the text. The Plugins section may eventually be split up and absorbed in the other sections if that makes more sense.
This flag turns warnings into errors, but since we are reorganizing the docs, we temporarily remove this. Once the work is completed, we can enable it once more.
This section is subdivided in 5 main categories: * How to run external codes * How to run multi-step workflows * How to work with data * How to manage your installation * How to package plugins The naming has been purposefully kept free of AiiDA specific jargon as these guides need to be quickly findable by relatively new users that after having run through a tutorial want to quickly know how to accomplish certain specific goals. Each section has its own document that will be presented as its own page with a number of subsections that present guides for specific goals. The sections and subsections are all created with the corresponding link labels for cross-referencing.
The Topics section will host documents that go in more-depth about certain concepts and will give detailed information about certain parts of the API.
The intro section contains the landing page with information about motivation and scope of the AiiDA software, as well as an overview of the documentation structure with links to other sections. This intro section also contains the instructions for how to install and setup AiiDA.
With reference to the GitHub issues Co-authored-by: Sebastiaan Huber <mail@sphuber.net>
… section Co-Authored-By: ramirezfranciscof <ramirezfranciscof@users.noreply.github.com>
The REST API reference is not yet auto-generated, like the command line reference section, but is moved to the "Reference" section nonetheless. Co-Authored-By: ramirezfranciscof <ramirezfranciscof@users.noreply.github.com>
This content already existed and has been largely moved as is. Just the style was adapted to match that of the new documentation, such as link labels, indentation and header styles.
The content that was envisioned for this section was originally divided over the "Concepts" and "Working" sections, which were itself roughly divided in information on "Processes", "Calculations" and "Workflows". The original idea was to nest the material on calculations and workflows within the global processes topic, since in the code the former are also sub classes of the latter. However, since there are also documentation on processes in general, I was not able to make this hierarchy work. Instead, "Calculations" and "Workflows" are now individul topics on the same level as "Processes". Each of these topics are roughly subdivided in a "Concepts" and "Usage" section, where the content from the latter came from the original "Working" directory. The concepts explains the concepts of the topic, where the usage really exposes and explains the API with all the nitty gritty details.
The content is largely untouched and mostly moved in to its new place in the scaffolding as is. There were slight changes in link labels and header characters to adhere to new style guide rules. Also fix various incorrect label references.
Removal of the SPHINX cheat sheet and visual aids page. Instructions for creating graphs has been moved to: https://github.com/aiidateam/aiida-core/wiki/Graph-Easy
This is a new section that is intended to describe the function of profiles and the various commands that can be used to work with them. Note that the explanation on the purpose and details of profiles is kept to a minimum as this is a How-to guide and is merely intended to help users with goal oriented problems. The section quickly explains the various profile commands: * verdi profile list * verdi profile setdefault * verdi profile show * verdi profile delete Information on how further configuration through profiles is reserved for the next how-to section "Configuring your installation".
This section describes how multiple instances of AiiDA can be isolated on the same machine, how tab-completion can be activated and how the `verdi config` command can be used to configure profile options. Except for the `verdi config` section, which is completely new, the other content has been adapted from existing documentation.
Add "How to package plugins": * add "Creating a plugin package" * add "Adding entry points" * add "Testing a plugin package" * add "Documenting a plugin package" * add "Publishing a plugin package" Also start adding the "plugins" topical guide. Co-authored-by: Carl Simon Adorf <carl.simon.adorf@gmail.com>
Until Github actions also allow these types of build artifacts.
Remove the internal custom `accordion` directive that was added for the `docs-revamp` branch and replace it with the `sphinx-panels` plugin. The `sphinx-copybutton` extension is added to allow users to easily copy code snippets to the clipboard.
Move (& update) documentation on internal AiiDA plugin system to the right place. Co-authored-by: Carl Simon Adorf <carl.simon.adorf@gmail.com>
Adding How-to delete data. Co-authored-by: Carl Simon Adorf <carl.simon.adorf@gmail.com>
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>
Currently, we state that multiple user setups for single AiiDA instances are not officially supported, and until we do, we do not describe the ways that people have used multiple users.
Add a tutorial to teach new users basic AiiDA concepts. Co-authored-by: Chris Sewell <chrisj_sewell@hotmail.com> Co-authored-by: Carl Simon Adorf <carl.simon.adorf@gmail.com>
Co-authored-by: Sebastiaan Huber <mail@sphuber.net> Co-authored-by: Carl Simon Adorf <carl.simon.adorf@gmail.com>
Co-authored-by: Carl Simon Adorf <carl.simon.adorf@gmail.com> Co-authored-by: Sebastiaan Huber <mail@sphuber.net>
Move in the sections on the `QueryBuilder` to the How-to section called "Finding and querying for data" The original text was too extensive for the purposes of the How-to and so it has been split in two. The detailed information on advanced queries will be added in another PR in the section "Topic - Database". The text for this How-to has been adapted from the original text with significant changes in the structure and simplifying the examples. Here wherever possible they use the `ArithmeticAddCalculation` for consistency with other sections and tutorials. The new structure is as follows: * Selecting entities * Retrieving results * Filters * Relationships * Projections
Revision of all sections within the first chapter. Co-authored-by: Carl Simon Adorf <carl.simon.adorf@gmail.com>
Add documentation for 'GroupPath'. Co-authored-by: Carl Simon Adorf <carl.simon.adorf@gmail.com>
* Exclude not yet migrated documentation source files. * Add pandas intersphinx link. * Remove empty verdi_user_guide.rst. * Fix sphinx references by either updating or removing them. * Move downloadable files into include subfolder. * Inline unreferenced file about moving PostgreSQL in "Tuning performance", * Fix various broken links and references.
794322a
to
d93ee54
Compare
Codecov Report
@@ Coverage Diff @@
## develop #4141 +/- ##
========================================
Coverage 78.74% 78.74%
========================================
Files 467 467
Lines 34454 34454
========================================
Hits 27128 27128
Misses 7326 7326
Continue to review full report at Codecov.
|
Using the 'todo::' directive.
b423d22
to
e1cd827
Compare
@sphuber It is not clear to me why GitHub marks the last commit as failed, but as far as I can tell, all checks passed. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good to me 👍
'external_links': [ | ||
{'url': 'http://www.aiida.net/', 'name': 'AiiDA Home'} | ||
], | ||
'github_url': 'https://github.com/aiidateam/aiida-core', |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
'github_url': 'https://github.com/aiidateam/aiida-core', | |
'github_url': 'https://github.com/aiidateam/aiida-core', | |
'twitter_url': 'https://twitter.com/aiidateam', |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this is just an optional cherry on the top, we can always add it later, if you can't be bothered to re-run all the tests again
* Update autogenerated `verdi` docs. * Fix `docs_path` in `docs/source/conf.py`. * Enable `warnings turn into errors` for docs-build. * Remove obsolete page `configuration`. * Move some unresolved references into todo-items. Sections `how-to:codes:transport` and `how-to:codes:scheduler` are not yet written. * Replace `sphinx.ext.imgmath` with `sphinx.ext.mathjax`. This way, latex is no longer required for documentation builds. * Add temporary fix for `pydata-sphinx-theme` issue #193. * Add AiiDA team twitter account to docs conf `html_theme_options` Co-authored-by: Chris Sewell <chrisj_sewell@hotmail.com>
e483a6d
to
8e69062
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's get this show on the road!
No description provided.