Document Filesystem Operations

Overview

We've changed a lot of stuff in the 4.0 release around filesystem. It's been documented alongside feature pull requests, but it's mostly been focused on the new File model abstraction. There's been lots of lower level changes that aren't documented in a coherent place, mainly around ModuleLoader and ModuleManifest APIs.

Acceptance Criteria

• Developers know how to get filesystem paths for modules, templates and project code
• Developers get consistent guidance in the context they're currently in (setting up a project, working with templates, etc)
• Developers know how to handle the public/ and mysite/ directories, regardless of their context (building themes, building modules, working with files)
• Developers know shortcuts for path operations

Tasks

• Better introduction to the "filesystem" topic (don't start with "uploadfield" in the second section)
• Pointers from "Getting Started > Directory Structure" to deeper info
• Examples on how to create files in Files > File Management
• Add instructions on how to handle module paths (both in "Files" and "Extending > Modules" sections)
• Point to Templates > Themes from "Files" and "Modules" sections regarding how they handle paths
• Document $project, how to configure it, how to use it to get custom paths. Both in Files > File Management and Configuration. Ensure that devs know that they can rename the mysite/ folder, and what effects that has
• Document Director::baseFolder() and alternate_base_folder in an obvious place (e.g. "Filesystem"). Can point to "Execution Pipeline" for details, but shouldn't require devs to find that document in the first place since it's much too advanced for this basic info
• Document SilverStripe\Core\Path

Review the existing Files > File Management, Getting Started > Directory Structure, Configuration, Extending > Modules, Templates > Themes, and Execution Pipeline guidance. Organise documentation for ModuleLoader, ModuleManifest, $project, Director::baseFolder(), alternate_base_folder, and SilverStripe\Core\Path; done means the listed acceptance criteria are covered coherently across the relevant contexts.