Add sections explaining exts_list options, and self.cfg in EasyBlocks

[kelseymh]

Following the discussion in EasyBlocks #3266, I've added a paragraph of text under "extensions parameters" explaining what each exts_list entry contains, and cross-referencing the "build parameters" section of the file.

I tried to use rst2html (provided with Python/3.6.6-foss-2018b) to check my work, but it apparently does not process :ref: directives (e.g., rst2html Implementing-easyblocks.rst generated a bunch of error messages).

Updated 25 Apr: I am also adding a section to Implementing-easyblocks.rst as well, describing how to use the self.cfg dictionary, per #618 .

[kelseymh]

This should not be merged as it is. It appears that not all of the "build parameters" can be used directly in exts_list entries, or else I'm just not doing it properly. Either way, it's going to need more than a bare sentence to explain how.

[boegel]

@kelseymh The documentation under the version-specific directory is automatically regenerated with every EasyBuild release (using the update-all-docs.sh script in docs/scripts), so your additions will get trashed the way they're done currently...

Perhaps it's better to add a subsection in https://easybuild.readthedocs.io/en/latest/Writing_easyconfig_files.html instead?

For which parameters are you seeing problems?

There indeed are a couple of exceptions, one is sources (you need to use source_tmpl instead, which implies that you can only have a single source per extension currently), but that's one we actually want to fix so sources also works as expected for extensions...

[kelseymh]

@boegel wrote:

The documentation under the version-specific directory is automatically regenerated with every EasyBuild release (using the update-all-docs.sh script in docs/scripts), so your additions will get trashed the way they're done currently...

Oops! Hence the directory name :-/ Okay, I can definitely back that out.

Perhaps it's better to add a subsection in https://easybuild.readthedocs.io/en/latest/Writing_easyconfig_files.html instead?

That works for me.

For which parameters are you seeing problems?

There indeed are a couple of exceptions, one is sources (you need to use source_tmpl instead, which implies that you can only have a single source per extension currently), but that's one we actually want to fix so sources also works as expected for extensions...

I was having trouble getting the filename+git_config substructure to work properly, but that's probably due to the sources/source_tmpl mismatch you just mentioned. Once I get this bit to work, then I'll have more confidence writing up guidance for others.

[kelseymh]

Added '(WIP)' to title to reflect that the organization of my changes needs to be modified per @boegel .

[ocaisa]

LGTM apart from the single comment

[kelseymh]

@ocaisa One question for you -- should these documentation updates be rolled out before the new feature in Framework PR #3294?

[ocaisa]

Even if you don't actually uses tags, we should give one here so the example gives best practice.

[ocaisa]

@kelseymh I haven't been close enough attention but of course you're right, easybuilders/easybuild-framework#3294 should come first.

[kelseymh]

How do I deal with the "codespell" failure on the "Docs build and installation" test?

https://github.com/easybuilders/easybuild/pull/617/checks?check_run_id=754862987#step:5:1

[ocaisa]

Fix the spelling error at https://github.com/easybuilders/easybuild/pull/617/checks?check_run_id=754862987#step:5:17 and add namd to the ignore words list in easybuild/.github/workflows/check_with_codespell.sh

[ocaisa]

@kelseymh argh sorry, Travis ci needs the ignore word as well

[ocaisa]

https://github.com/easybuilders/easybuild/blob/develop/.travis.yml#L16

[kelseymh]

@ocaisa @boegel This PR is still listing "one change requested", but I can't figure out what the change is. Following the "See review" takes me to @ocaisa 's comment about using a tag, rather than a branch or SHA in my example, which I implemented. I'm hoping this could get re-reviewed with the current version so it can roll out to 4.2.2 along with the new code it's documenting.

[ocaisa]

Thanks for the effort you've gone to on this @kelseymh , a couple more suggestions but otherwise good to go

[ocaisa]

Going in, thanks @kelseymh !