Epic: Updating the ASE Documentation and Tutorials

Summary

This issue tracks a proposed redesign and update of the ASE documentation, webpage and tutorials, as discussed in Breakout Group 3 at the 2025 CECAM workshop "The atomic simulation environment ecosystem: Present and perspectives."

The ASE documentation is currently not very beginner friendly. It is hard to navigate, not consistent in formating and missing documentation for some functions or objects. The ASE tutorials are formulated as exercises and in many cases use external calculators that would need to be installed. Both make it difficult to get started.

The description here has been adapted from the HackMD Notes developed at the workshop which also contains more details.

Motivation

  • The ASE documentation and tutorials currently do not make it easy to get started with using ASE
  • The current ASE webpage is difficult to navigate
  • Missing documentation for some functions/objects

Goals

  • Make it easier to get started with ASE
  • Consistent documentation and tutorials to allow easier use and understanding of ASE
  • Restruction of the ASE webpage to make it more engaging and accessible
  • Keep ASE documentation up to date

Proposed Design

Proposed Re-Design for Website structure

  • Home (landing page, not in the TOC)
  • About
  • Contact
  • Installation
  • Tutorials/User guide
    • Python
    • ASE
    • Getting started
    • The current contents of 'tutorials'
    • Issues (Link to the Gitlab issues page)
    • Code snippets (something that is useful, too much to put in docstring but too little to make a full tutorial about)
    • Command line tool
    • Tips and tricks
    • Making movies (currently in 'development')
    • FAQ
  • Development
    • API Documentation (currently 'modules')
    • Developers guide (currently 'development')
  • Gallery
  • ASE ecosystem
  • Events
    • ASE Workshop 2019 - Chalmers
    • Ase Workshop 2023 - Copenhagen
    • ASE workshop 2023 - Daresbury
    • ASE Workshop 2025 - Lausanne
  • Release notes

Proposed Design for Documentation

  • describe all input parameters (with type)
  • describe basic functionality of the function
  • basic working example

Proposed Design for Tutorials

  • if possible in a Jupyter notebook

Pseudocode:

# Intro
{Descriptive title
In this tutorial you will learn...}

# Imports:
from ase import ...

# Main tutorial blocks. Repeat as needed
{Description of upcoming code/plan/step}

Code block

(Possibly output/plots. If so, commentary.)

Implementation Plan

  • Form an ASE Documentation group (Doc-group) to coordinate tutorials, maintaining up-to-date documentation and website
  • Write templates and guidelines for writing documentation and tutorials
  • Update/restructure existing tutorials to match template and to make sure they work without external calculator
  • Enforce new contribution to follow documentation guidelines before being merged
  • Update webpage to new structure
  • Create git issues for documentation that does not work or is not up to date

Discussion Points

  • How can we form the Doc-group group?
  • Who is responsible for reviewing the changes of documentation/tutorials?
  • Do we need new tutorials? If so, where do we get them from?
  • If the tutorials are done as interactive Jupyter notebooks, where can we host them?