Module chapter rewrite

[NotTheDr01ds]

As discussed with @kubouch in #1585, this is a pretty major rewrite of the Modules Chapter, along with a few tangential updates to other chapters.

High-level

• Divides Modules into two parts:

  • Using
  • Creating

  This allows newer users who just need to use first-or-third-party modules to skip all of the "Creating" part (which was the major focus in the previous version of the chapter)

• Removes much of the explanation on how to import modules from the Standard Library chapter, since we can now simply point to "Using Modules". The Standard Library chapter is now much shorter as a result.

---

Minutiae

Modules Overview

Briefly covers what they are as well as what they can contain.

Using Modules

• Adds a brief section on "Installing" - It's not much, but we can flesh this out later as the story improves (i.e., Nupm). Mostly for now, it punts it to the module's documentation.
• Relies on the Standard Library for many of its examples, since it's available "out-of-the-box" to all users. No need to force new users to write a module in order to demonstrate using one.
• There was a brief section in the previous Modules chapter on the "Import Pattern'. This has been moved to the "Using" chapter, of course. It uses different examples so that it doesn't rely on those written in "Creating"
• Added more detail to the import pattern, including mention of relative paths search from $env.NU_LIBS_PATH
• Adds information on how to access constants imported from modules (since I obviously had a hard time figuring that out myself)
• "Hiding" was also moved to the "Using" chapter - There was an erroneous/outdated statement that hide could also hide environment variables (that's now hide-env) that I nixed entirely.
• "See also" section mentioning adding modules to the configuration and Overlays

Creating Modules

• Rewrote all examples to be a bit closer to (but not completely) "real world" scenarios. I hope it's okay if we bid farewell to the venerable greetings.nu? I believe the new examples are a bit more clear and even (mostly) more concise.

• Removed "inline" as an example of how to create a module. Replaced with a tip:

  While it's possible to use the module command to create a module directly at the commandline, it's far more useful and common to store the module definitions in a file for reusability.

• The discussion of main is important and is moved up closer to the beginning of the chapter. Thanks @132ikl for adding that in the first place. As promised in the review of that PR, I've cc'd you on this one. You should see, I believe, every concept you mentioned in this rewrite.

• The previous version of the chapter had this tidbit:

  Submodules are modules inside modules. They are automatically created when you call use on a directory: Any .nu files inside the directory are implicitly added as submodules of the main module. There are two more ways to add a submodule to a module:

  That just seems wrong or outdated. I've removed it. Now the section focuses on export module and export use to create submodules.

• Removed the redundant note about module without export ... It was already covered above as well as in one of the examples.

• The previous version of the chapter used "namespace" and "prefix" frequently. As @kubouch mentioned, these are not well-defined terms in Nushell. For the most part, I tended to rewrite/reword sections with these terms.

• Moved the last two examples (VirtualEnv/Conda and "Dumping Files in a Directory") to the Cookbook. They seem better aligned there.

Standard Library

• Removed the section on "viewing source" for Standard Library as it was (a) incomplete, (b) probably not altogether useful, and (b) my idea in the first place, so I didn't feel bad about it ;-)

[132ikl]

Awesome, I'll take a look when I get the chance

[fdncred]

LGTM

[fdncred]

Thanks

[132ikl]

Finally got around to taking a look at this. Really good stuff! I definitely understand modules better now 😄

I know this is merged already, but figured it was easiest to leave feedback in a review anyways.

[132ikl]

Not sure if this should have its own header if its only content is a infobox ("importantbox"?)

[NotTheDr01ds]

Yeah, not my favorite style either, but I want a header so that it shows up in the ToC and sidebar, but I think it's useful as a callout as well given its importance.