Docs: scaffolding for the "Intro" section #4011

chrisjsewell · 2020-05-01T09:24:47Z

Aim

From wiki:

Getting started (intro/) - Landing page for new users, should provide motivation, code snippets, and links to the various resources, including on how to install the package, test it online, and the tutorial.

Outline

From Google Doc Outline, it should follow this outline:

Landing Page (main index): Like pandas (https://pandas.pydata.org/docs/index.html)

At the top: mission statement; with link to the features page on aiida.net
Why use AiiDA (features, basic examples) max 1-2 minutes; could be part of panels
Below 6 panels (this gives a good overview of the documentation structure):
- Getting Started
- Tutorial
- How-To
- Topics
- API Reference
- Development

"quick-setup" of AiiDA (intro/get_started): final state: verdi status is green (+ localhost computer is setup?)

MyBinder (recommended for testing)
Conda (recommended for production) + includes profile setup
Next steps
- Recommend tutorial
- Provide a few links for different user profiles
- How to run workflows for pure Python lightweight computations
- How to run workflows for compute-intensive codes (DFT, MD etc.)
- How to run workflows on supercomputers

Detailed Installation guides (intro/installation): incorporate all existing documentation +

Pip + Link to how to install services
In-depth/alternative installation methods
Services for various systems
Conda in detail
Pip in detail
QuantumMobile
AiiDA lab

Troubleshooting (intro/troubleshooting): incorporate existing troubleshooting

Outstanding Issues

We are currently missing the "Why use AiiDA" section. I'm not sure where we landed on how much of this should be on the landing page and/or whether we needed the additional intro/about section. The features section of the landing page has currently been deleted, but this should be added back in, in some form. Also relevant is that @ltalirz is working on a testimonial section.
Check that everyone is OK with adding the sphinx-panels dependency
@sphuber didn't like the current look of the panels. I think this is just a matter of playing around with the CSS
We don't yet have the MyBinder setup (I imagine this will be a separate issue to add to project)
Come to a consensus on if Conda is the correct route for the "quick-install"
The next steps uses a new (currently internal) extension I have added. This would effectively replace the existing sphinxcontrib-details-directive dependency, and should get consensus that this is OK.
The "next steps" is not yet populated (I imagine this will be a separate issue to add to project)

Note some initial discussion has already taken place in csadorf#25

Co-authored-by: Leopold Talirz <leopold.talirz@gmail.com>

docs/source/_extensions/accordion.py

codecov · 2020-05-01T09:39:01Z

Codecov Report

Merging #4011 into docs-revamp will decrease coverage by 0.02%.
The diff coverage is n/a.

@@               Coverage Diff               @@
##           docs-revamp    #4011      +/-   ##
===============================================
- Coverage        78.46%   78.45%   -0.01%     
===============================================
  Files              461      461              
  Lines            34077    34077              
===============================================
- Hits             26736    26732       -4     
- Misses            7341     7345       +4

Flag	Coverage Δ
#django	`70.49% <ø> (ø)`
#sqlalchemy	`71.35% <ø> (-0.01%)`	⬇️

Impacted Files	Coverage Δ
aiida/orm/utils/log.py	`76.67% <0.00%> (-16.66%)`	⬇️
aiida/transports/plugins/local.py	`80.47% <0.00%> (+0.26%)`	⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 25052c0...76270ca. Read the comment docs.

greschd · 2020-05-01T09:40:54Z

Regarding 6.:

What are the advantages of accordion, compared to the <details> tag?
What happens if JavaScript is disabled? Does it default to folded or unfolded content?

I don't think we can get rid of the details directive dependency completely, as it's also used in the aiida.sphinxext for expandable namespace input / output descriptions.

chrisjsewell · 2020-05-01T09:47:44Z

@sphuber didn't like the current look of the panels. I think this is just a matter of playing around with the CSS

One thing that I wanted to briefly mention, although it is most probably not something I expect us to implement, is that currently using CircleCI for documentation integration testing has a big benefit over GitHub Actions, because it can provide HTML build artefacts. For example in: executablebooks/sphinx-panels#3, you get a link that directly opens the newly built documentation for review:

csadorf · 2020-05-01T09:50:14Z

One thing that I wanted to briefly mention, although it is most probably not something I expect us to implement, is that currently using CircleCI for documentation integration testing has a big benefit over GitHub Actions, because it can provide HTML build artefacts.

That's a really nice feature and we could consider to use circle-ci specifically for this purpose. @chrisjsewell I'm wondering whether it would be possible to implement something similar in GitHub actions as well though. Uploading artifacts is not that difficult, I just don't know about "serving" the HTML so that you can just open it directly without downloading first.

chrisjsewell · 2020-05-01T09:53:04Z

Regarding 6.:

What are the advantages of accordion, compared to the
tag?
What happens if JavaScript is disabled? Does it default to folded or unfolded content?

Its just better looking TBH, and mirrors better the pandas doc section that we were looking to replicate.
The JS is copied from sphinx-togglebutton, and will be folded by default. Note this directive may eventually be incorporated into that repo: executablebooks/sphinx-togglebutton#11

Note also that the code/css follows closely this guide: https://www.w3schools.com/howto/howto_js_collapsible.asp

chrisjsewell · 2020-05-01T09:55:28Z

I'm wondering whether it would be possible to implement something similar in GitHub actions as well though

Unfortunately at the moment no. I would refer you to this issue, roughly tracking the status of this feature in Github actions: spatialaudio/nbsphinx#361

csadorf

Really nice! First set of recommendations to change up the language a little bit on the landing page. I'll start reviewing the installation instructions next.

docs/source/_extensions/_static/accordian.css

docs/source/_extensions/_static/accordian.js

docs/source/conf.py

docs/source/index.rst

greschd · 2020-05-01T10:31:43Z

Its just better looking TBH, and mirrors better the pandas doc section that we were looking to replicate.

Yeah I'm not against this in principle, just wondering if the same (in terms of style) could be achieved with custom CSS for the details tag. Plain HTML has the advantage of also working for the subset of users who disable JS.
The content being hidden by default is good (that's kinda the point), but when it can't be un-collapsed (without JS) the content should still be shown.

csadorf

Provided a few suggestions for the conda installation instructions.

csadorf · 2020-05-01T10:26:52Z

docs/source/intro/get_started.rst

+Getting Started
+****************
+
+Installation


Suggested change

Installation

Install with conda

And that should then be on its own page.

I'm not clear what you are expecting to remain on this page. If we move the conda install to a separate page, then surely there will be nothing left on this page?

The panels for the main installation routes is left.

csadorf · 2020-05-01T10:27:41Z

docs/source/intro/get_started.rst

+There are numerous routes to setting up the full AiiDA environment, depending on your use case.
+Here we first provide the simplest approach for installation on your local computer.


I think this paragraph should remain on the "Getting started" landing page after we have moved the conda instructions to a separate page.

csadorf · 2020-05-01T10:28:21Z

docs/source/intro/get_started.rst

+
+    $ conda create -n aiida -c conda-forge aiida-core aiida-core.services
+    $ conda activate aiida
+    $ reentry scan


Could this be rolled into conda activate aiida?

Possibly. Me and @ltalirz have already discussed this for example in chrisjsewell/activate_aiida#4, and I think he is looking into it

csadorf · 2020-05-01T10:29:32Z

docs/source/intro/get_started.rst

+.. code-block:: console
+
+    $ conda create -n aiida -c conda-forge aiida-core aiida-core.services
+    $ conda activate aiida


This activates the services, correct? I think we should either move this into a separate code block or mention right after, that this will need to be run after every reboot. Ideally, we can avoid this all-together in the future, but for now we need to mention that.

This activates the services, correct?

No this is just activating the conda enviroment (aiida is the environment name, maybe that is misleading?). It does need to be run when "entering" a new terminal though, i.e. to set the environment

Sorry, I completely misread this, sorry.

csadorf · 2020-05-01T10:31:10Z

docs/source/intro/get_started.rst

+.. note::
+
+    You can also install ``aiida-core`` from `PyPi <https://pypi.org/project/aiida-core>`_


I think we should be more generic here and just say "Click here for alternative installation methods.". This is for users who were directed to this page (e.g. from a Stack Overflow answer or some other source), but actually don't want to use conda.

csadorf · 2020-05-01T10:31:52Z

docs/source/intro/get_started.rst

+.. code-block:: console
+
+    $ initdb -D mylocal_db
+    $ pg_ctl -D mylocal_db -l logfile start


Could this be rolled into conda activate aiida?

see above comment

csadorf · 2020-05-01T10:33:20Z

docs/source/intro/get_started.rst

+
+.. code-block:: console
+
+    $ rabbitmq-server -detached


Similar question, make part of conda activate aiida?

see above comment

docs/source/intro/get_started.rst

csadorf · 2020-05-01T10:35:55Z

Its just better looking TBH, and mirrors better the pandas doc section that we were looking to replicate.

Yeah I'm not against this in principle, just wondering if the same (in terms of style) could be achieved with custom CSS for the details tag. Plain HTML has the advantage of also working for the subset of users who disable JS.
The content being hidden by default is good (that's kinda the point), but when it can't be un-collapsed (without JS) the content should still be shown.

@greschd I agree that this should work without JS, but I would be in favor of creating an issue for that and then resolving that down the line. Our priority right now should be to get something online as soon as possible.

chrisjsewell · 2020-05-01T10:57:51Z

just wondering if the same (in terms of style) could be achieved with custom CSS for the details tag

Err, well not according to this blog: Why <details> is Not an Accordion. I guess that's a group decision on whether to support JS, to improve the style. I'm in favour, and it appears pandas are as well 😬

On a related note (again really for a separate issue) pandas does not require the custom JS, because it uses a "more modern" bootstrap theme (see here re collapse), which I am in favour of moving to: https://pypi.org/project/pydata-sphinx-theme/

greschd · 2020-05-01T11:21:20Z

Ok, if I understand correctly the problem is that headings inside <details> are not handled properly, and especially lead to accessibility concerns. I think that's a valid enough reason not to use <details>, so it's ok for me to go ahead with this as-is and resolve the no-JS compatibility later as @csadorf suggests.

To be honest I'm also a bit out of my depth here, frontend is not really my specialty.

Co-authored-by: Carl Simon Adorf <carl.simon.adorf@gmail.com>

docs/source/index.rst

Co-authored-by: Carl Simon Adorf <carl.simon.adorf@gmail.com>

…sewell/aiida_core into docs-revamp-intro-install

chrisjsewell · 2020-05-01T14:54:20Z

docs/source/intro/get_started.rst

+
+.. code-block:: console
+
+    $ reentry scan


I have figured out how best to succinctly explain this command yet

chrisjsewell · 2020-05-01T14:56:15Z

TODO:

there's currently a CSS annoyance with long code blocks not allowing panels to shrink

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.

chrisjsewell and others added 11 commits April 29, 2020 18:03

Intial draft of installation guide

d44f7df

Add basic accordian directive

8d1806b

correct javascript

c505700

add indicator

31426bf

add panels sphinx extension

c946c9f

Update docs/source/_extensions/_static/accordian.css

19bfdfb

Co-authored-by: Leopold Talirz <leopold.talirz@gmail.com>

improve directives and add link-box

60335de

add to doc string

e765709

Update landing page

3e506b9

update toc pages

0b5dc40

move panels extension to external dependency

40fa5e1

chrisjsewell requested a review from csadorf May 1, 2020 09:26

greschd reviewed May 1, 2020

View reviewed changes

docs/source/_extensions/accordion.py Outdated Show resolved Hide resolved

csadorf mentioned this pull request May 1, 2020

Intial draft of installation guide csadorf/aiida-core#25

Closed

csadorf suggested changes May 1, 2020

View reviewed changes

chrisjsewell and others added 3 commits May 1, 2020 12:24

Adress review suggestions

c6fdeb3

fix typo accordian -> accorion

80449ce

Update docs/source/intro/get_started.rst

5209849

Co-authored-by: Carl Simon Adorf <carl.simon.adorf@gmail.com>

csadorf reviewed May 1, 2020

View reviewed changes

docs/source/index.rst Outdated Show resolved Hide resolved

chrisjsewell and others added 3 commits May 1, 2020 13:40

Update docs/source/index.rst

c2af934

Co-authored-by: Carl Simon Adorf <carl.simon.adorf@gmail.com>

update

0e5a0a8

Merge branch 'docs-revamp-intro-install' of https://github.com/chrisj…

4a68f39

…sewell/aiida_core into docs-revamp-intro-install

chrisjsewell commented May 1, 2020

View reviewed changes

pre-commit fix

f5e0895

chrisjsewell mentioned this pull request May 1, 2020

Docs: intro/get_started #4026

Closed

add open issues

76270ca

sphuber changed the title ~~Add initial skeleton for intro section~~ Docs: scaffolding for the "Intro" section May 1, 2020

chrisjsewell mentioned this pull request May 1, 2020

Docs: Consider using CircleCI for documentation CI #4028

Closed

csadorf marked this pull request as ready for review May 1, 2020 15:34

csadorf approved these changes May 1, 2020

View reviewed changes

csadorf merged this pull request into aiidateam:docs-revamp May 1, 2020

chrisjsewell deleted the docs-revamp-intro-install branch January 27, 2021 04:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: scaffolding for the "Intro" section #4011

Docs: scaffolding for the "Intro" section #4011

chrisjsewell commented May 1, 2020 •

edited

Loading

codecov bot commented May 1, 2020 •

edited

Loading

greschd commented May 1, 2020

chrisjsewell commented May 1, 2020

csadorf commented May 1, 2020 •

edited

Loading

chrisjsewell commented May 1, 2020 •

edited

Loading

chrisjsewell commented May 1, 2020

csadorf left a comment

greschd commented May 1, 2020

csadorf left a comment

csadorf May 1, 2020

chrisjsewell May 1, 2020

csadorf May 1, 2020

csadorf May 1, 2020

csadorf May 1, 2020

chrisjsewell May 1, 2020 •

edited

Loading

csadorf May 1, 2020

chrisjsewell May 1, 2020

csadorf May 1, 2020

csadorf May 1, 2020

csadorf May 1, 2020

chrisjsewell May 1, 2020

csadorf May 1, 2020

chrisjsewell May 1, 2020

csadorf commented May 1, 2020 •

edited

Loading

chrisjsewell commented May 1, 2020 •

edited

Loading

greschd commented May 1, 2020

chrisjsewell May 1, 2020

chrisjsewell commented May 1, 2020

		There are numerous routes to setting up the full AiiDA environment, depending on your use case.
		Here we first provide the simplest approach for installation on your local computer.

		.. note::

		You can also install ``aiida-core`` from `PyPi <https://pypi.org/project/aiida-core>`_

Docs: scaffolding for the "Intro" section #4011

Docs: scaffolding for the "Intro" section #4011

Conversation

chrisjsewell commented May 1, 2020 • edited Loading

Aim

Outline

Outstanding Issues

codecov bot commented May 1, 2020 • edited Loading

Codecov Report

greschd commented May 1, 2020

chrisjsewell commented May 1, 2020

csadorf commented May 1, 2020 • edited Loading

chrisjsewell commented May 1, 2020 • edited Loading

chrisjsewell commented May 1, 2020

csadorf left a comment

Choose a reason for hiding this comment

greschd commented May 1, 2020

csadorf left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrisjsewell May 1, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

csadorf commented May 1, 2020 • edited Loading

chrisjsewell commented May 1, 2020 • edited Loading

greschd commented May 1, 2020

Choose a reason for hiding this comment

chrisjsewell commented May 1, 2020

chrisjsewell commented May 1, 2020 •

edited

Loading

codecov bot commented May 1, 2020 •

edited

Loading

csadorf commented May 1, 2020 •

edited

Loading

chrisjsewell commented May 1, 2020 •

edited

Loading

chrisjsewell May 1, 2020 •

edited

Loading

csadorf commented May 1, 2020 •

edited

Loading

chrisjsewell commented May 1, 2020 •

edited

Loading