Azure docs rewrite

[adamrtalbot]

It started as a quick update to the docs and turned into a full re-write.

Changes:

• restructures Azure docs to be more logical
  • authentication
  • storage
  • compute
  • advanced
• Removes redundancy and clarifies some bits
• Simplifies where possible
• Guides user from A to Z in a more straightforward manner

[netlify]

✅ Deploy Preview for nextflow-docs-staging ready!

Name	Link
🔨 Latest commit	845423a
🔍 Latest deploy log	https://app.netlify.com/projects/nextflow-docs-staging/deploys/6840717d5af8cb0008fb2691
😎 Deploy Preview	https://deploy-preview-6087--nextflow-docs-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[christopher-hakkaart]

The number of suggestions looks much worse than it is. I try to do suggestions on separate lines so you can screen and accept and reject specific comments rather than edit the suggestion.

[adamrtalbot]

@christopher-hakkaart this is ready for a re-review.

[christopher-hakkaart]

@adamrtalbot I pushed a bunch of changes rather than loading the PR with suggestions again.

Noteworthy changes:

• Made passive sentences active by moving the second half of the sentences with a comma to the front.
• Aligned punctuation and style for lists with and without colons.
• Some minor voice and tense alignments (e.g., removing "will" from sentences).
• Move all H4 headings (####) up to H3 (###), H4 is too deep in the navigation.
• Corrected capitalization of Azure-related words.
• Minor punctuation fixes.

Feel free to revert anything you disagree with.

I'll give it a quick look again tomorrow with fresh eyes and make any final suggestions. Overall, it's looking really good.

[adamrtalbot]

This is a bit messy and hard to follow:

Perhaps we should move the comments and placeholder comments out of the numbered points to keep the flow simple.

[adamrtalbot]

Suggested change

	1. Create an Azure Batch account in the Azure portal.
	2. Increase the quotas in your Azure Batch account to the pipeline's needs.
	:::{note}
	Quotas impact the number of pools, CPUs, and jobs you can create.
	:::
	3. Create a storage account and Azure Blob Storage in the same region as the Batch account.
	4. Configure Nextflow to submit processes to Azure Batch using configuration. For example:
	```groovy
	process {
	executor = 'azurebatch'
	}
	azure {
	storage {
	accountName = '<STORAGE_ACCOUNT_NAME>'
	}
	batch {
	location = '<LOCATION>'
	accountName = '<BATCH_ACCOUNT_NAME>'
	autoPoolMode = true
	allowPoolCreation = true
	}
	}
	```
	Replace the following:
	- `STORAGE_ACCOUNT_NAME`: your account name
	- `LOCATION`: your Azure region
	- `ACCOUNT_NAME`: your batch account name
	:::{note}
	The above snippet excludes authentication for Azure services. See [Authentication](#authentication) for more information.
	:::
	5. Launch your pipeline with the above configuration and add a working directory on Azure Blob Storage:
	```bash
	nextflow run <PIPELINE_NAME> -w az://<BLOB_STORAGE>/
	```
	Replace the following:
	- `PIPELINE_NAME`: your pipeline, for example, `nextflow-io/rnaseq-nf`
	- `BLOB_STORAGE`: your Azure Blob Storage from the storage account defined in your configuration
	:::{tip}
	You can list Azure regions with: `az account list-locations -o table`
	:::
	1. Create an Azure Batch account in the Azure portal.
	2. Increase the quotas in your Azure Batch account to the pipeline's needs.
	3. Create a storage account and Azure Blob Storage in the same region as the Batch account.
	4. Configure Nextflow to submit processes to Azure Batch using configuration. For example:
	```groovy
	process {
	executor = 'azurebatch'
	}
	azure {
	storage {
	accountName = '<STORAGE_ACCOUNT_NAME>'
	}
	batch {
	location = '<LOCATION>'
	accountName = '<BATCH_ACCOUNT_NAME>'
	autoPoolMode = true
	allowPoolCreation = true
	}
	}
	```
	5. Launch your pipeline with the above configuration and add a working directory on Azure Blob Storage:
	```bash
	nextflow run <PIPELINE_NAME> -w az://<BLOB_STORAGE>/
	```
	:::{note}
	The above snippet excludes authentication for Azure services. See [Authentication](#authentication) for more information.
	:::
	Replace the following:
	- `STORAGE_ACCOUNT_NAME`: your account name
	- `LOCATION`: your Azure region
	- `ACCOUNT_NAME`: your batch account name
	- `PIPELINE_NAME`: your pipeline, for example, `nextflow-io/rnaseq-nf`
	- `BLOB_STORAGE`: your Azure Blob Storage from the storage account defined in your configuration
	:::{note}
	Quotas impact the number of pools, CPUs, and jobs you can create.
	:::
	:::{tip}
	You can list Azure regions with: `az account list-locations -o table`
	:::

Maybe?

[christopher-hakkaart]

I prefer to have these attached to the relevant step. For a user who may follow the steps one at a time, it doesn't make sense to have them at the bottom. E.g., considerations for setting quotas should be considered when setting the quota, not after the whole thing is set up.

We could try and wrap it into the same point to avoid the note:

Submit a request through the Azure Portal's Quotas page to increase your Azure Batch account limits on pools, CPUs, and jobs based on your pipeline's resource needs.

[adamrtalbot]

I've tried to simplify it with c422f6a.

• Moved notes to within the bullet points (if you have something to say say it properly)
• Removed config items and referred to the authentication section

[adamrtalbot]

The language is a bit weird here.

[adamrtalbot]

@christopher-hakkaart all looks good - I'm never sure about punctuation for what is an Azure product and what isn't.

If we aren't using 4th level headings we should remove "Pool management" and just have a few other 3rd level headings, I've left a comment.

[christopher-hakkaart]

Thanks @adamrtalbot - agree with your point about headings. I've accepted your suggestions.

I've also asked @justinegeffen to look at this PR as well. As I made so many changes/suggestions it would be good to get a second review from the style side. We don't want to slow this PR down, so if the review is taking too long, we can look at merging this now, and then making a second PR to fix any style-related issues I introduced.

Regarding the naming, I never know that to do either. I took notes on everything I wasn't sure about and checked as I went. I'll write up a cheat sheet for future reference.

[justinegeffen]

Suggested change

	5. Configure Nextflow to submit processes to Azure Batch by setting the process.executor directive to `azurebatch`.
	5. Configure Nextflow to submit processes to Azure Batch by setting the `process.executor` directive to `azurebatch`.

[justinegeffen]

Suggested change

	2. Increase the quotas in your Azure Batch account to the pipeline's needs. Quotas impact the number of pools, CPUs, and jobs you can create.
	2. Increase the quotas in your Azure Batch account to support the pipeline's needs. Quotas impact the number of pools, CPUs, and jobs you can create.

[justinegeffen]

@adamrtalbot, does this suggestion make sense in the context?

[justinegeffen]

Suggested change

	2. Configure the required role assignments. See [Required Roles](#required-roles) for more information.
	2. Configure the required role assignments. See [Required roles](#required-roles) for more information.