Convert step-by-step guide to markdown

[forsyth2]

Converting the original step-by-step guide from Confluence to Markdown.

I created an initial pull request on my fork rather than https://github.com/E3SM-Project/E3SM itself so that I could make a draft PR and not interfere with any established best practices on the main repo.

[github-actions]

PR Preview Action v1.4.7
🚀 Deployed preview to https://forsyth2.github.io/E3SM/pr-preview/pr-1/
on branch gh-pages at 2024-04-03 23:57 UTC

[forsyth2]

Primary updates

Most obviously, the guide has been converted from Confluence to Markdown. Other differences:

• The guide now refers to the v3 template script.
• Cori references are replaced with Perlmutter.
• I removed references to code older than Unified 1.6.0, since that is significantly out of date by now.
• Similarly, I removed a warning about zstash check reports success even if exceptions occur E3SM-Project/zstash#167 since that has been resolved.
• Misc. readability improvements

The full output can be seen at https://github.com/forsyth2/E3SM/blob/forsyth2/docs/update-guide/docs/step_by_step_guide.md

Documentation building

I followed the directions at Developing Documentation, but I ended up getting:

Traceback (most recent call last):
  File "/gpfs/fs1/home/ac.forsyth2/mkdocsenv/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/gpfs/fs1/home/ac.forsyth2/mkdocsenv/lib64/python3.6/site-packages/click/core.py", line 1128, in __call__
    return self.main(*args, **kwargs)
  File "/gpfs/fs1/home/ac.forsyth2/mkdocsenv/lib64/python3.6/site-packages/click/core.py", line 1053, in main
    rv = self.invoke(ctx)
  File "/gpfs/fs1/home/ac.forsyth2/mkdocsenv/lib64/python3.6/site-packages/click/core.py", line 1659, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/gpfs/fs1/home/ac.forsyth2/mkdocsenv/lib64/python3.6/site-packages/click/core.py", line 1395, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/gpfs/fs1/home/ac.forsyth2/mkdocsenv/lib64/python3.6/site-packages/click/core.py", line 754, in invoke
    return __callback(*args, **kwargs)
  File "/gpfs/fs1/home/ac.forsyth2/mkdocsenv/lib64/python3.6/site-packages/mkdocs/__main__.py", line 192, in build_command
    build.build(config.load_config(**kwargs), dirty=not clean)
  File "/gpfs/fs1/home/ac.forsyth2/mkdocsenv/lib64/python3.6/site-packages/mkdocs/commands/build.py", line 257, in build
    config = config['plugins'].run_event('config', config)
  File "/gpfs/fs1/home/ac.forsyth2/mkdocsenv/lib64/python3.6/site-packages/mkdocs/plugins.py", line 102, in run_event
    result = method(item, **kwargs)
  File "/gpfs/fs1/home/ac.forsyth2/mkdocsenv/lib64/python3.6/site-packages/mkdocs_monorepo_plugin/plugin.py", line 52, in on_config
    new_docs_dir = self.merger.merge()
  File "/gpfs/fs1/home/ac.forsyth2/mkdocsenv/lib64/python3.6/site-packages/mkdocs_monorepo_plugin/merger.py", line 62, in merge
    copytree(source_dir, dest_dir, dirs_exist_ok=True)
TypeError: copytree() got an unexpected keyword argument 'dirs_exist_ok'

I even set up a new clone of E3SM to work in, and followed the relevant directions on the Development Getting Started Guide.

I wasn't able to build the docs before or after I made the changes here.

Other notes

I was trying to see if Confluence-to-Markdown exporters exist, but it looked like that could only be accomplished using non-Atlassian plugins. E.g., here and here. Markdown Exporter for Confluence is such an app.

But I ultimately decided to just port the guide over manually for two reasons:

1. There were a number of changes that needed to be made, so it gave me a chance to go through the guide line-by-line.
2. I wasn't sure about the security constraints of our Confluence space -- e.g., if we needed to get apps approved first. For example, Installing Marketplace apps mentions "A note about safety: apps are very powerful, they can change the behavior of almost any part of the Atlassian application. It's very important that you trust an app before you install it. Always be aware of where (and who) an app comes from."

[forsyth2]

On second thought, I think this is probably at the point where's it's ready to be a PR in the main repo. I will close this one.

[forsyth2]

Closing, see E3SM-Project#6326 instead.