Docs revamp #4141
Merged
Docs revamp #4141
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
csadorf
force-pushed
the
docs/re-enable-ci
branch
from
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.
csadorf
force-pushed
the
docs/re-enable-ci
branch
2 times, most recently
from
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. |
chrisjsewell
reviewed
Jun 2, 2020
| '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.
Suggested change
| '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.
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
1 task
* 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>
sphuber
force-pushed
the
docs/re-enable-ci
branch
from
e483a6d to
8e69062
Compare
sphuber
approved these changes
Jun 2, 2020
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.