aiidateam / aiida-quantumespresso

The official AiiDA plugin for Quantum ESPRESSO
https://aiida-quantumespresso.readthedocs.io
Other
53 stars 78 forks source link

Docs: use `sphinx-book-theme` #946

Closed mbercx closed 1 year ago

mbercx commented 1 year ago

@sphuber went down a little rabbit hole when I was writing the docs for the create_magnetic_allotrope function. Wanted to add margin notes, but then saw we weren't using sphinx_book_theme. Then I realised I can also probably just add this as an extension to get the margin directive, but I kind of liked the theme better than pydata_sphinx_theme. So I made some small tweaks here and there and wanted to ask your opinion.

I can also add the header bar here and tweak the sidebar again, but right now our documentation feel a little too small to add a head bar for it.

I swear I didn't make this change just to make my logo more prominent again. Although I did feel compelled to add a dark mode version for it. 😇

To make you more amenable to this change, I come bearing gifts:

  1. Intersphinx mapping to aiida-core is fixed!
  2. No more warnings during docs build related to targets not being found!
  3. Badges! Everyone loves badges!
  4. An awesome supercool AiiDA logo that links to www.aiida.net.
sphuber commented 1 year ago

To make you more amenable to this change, I come bearing gifts:

You forgot the biggest gift of all: no emojis to be found! 🥳 You have my blessing, happy to approve the changes

mbercx commented 1 year ago

Great! Maybe at some point it makes sense to bring back the header. I was also wondering we should perhaps remove empty "to be added" sections from the toctree, now it just clutters up things.

Finally, the "Topics" are now just automatically generated input/output specs of the processes. I would actually remove the Topics section entirely for now (though to be added again to discuss e.g. protocols, restarting, etc...), and move the current topics content to Reference, but then as e.g. "Process specification".