Documentation incorrectly lists --project-root and --config-path parameters for oranda build

[lynnpepin]

Loving Oranda!! I just now found an issue where the docs refer to a feature that seems to not yet have been implemented. I wasn't able to find contributing guidelines, so I apologize if this issue isn't formatted correctly.

TLDR: The Oranda docs suggests one can pass a parameter --project-root to oranda build, but one can't.

As of 0.6.1, this does not work, and oranda build -h does not show the --project-root or --config-path parameters:

oranda build --help
Build an oranda site

Usage: oranda build [OPTIONS]

Options:
      --json-only
          Only build the artifacts JSON file (if applicable) and other files that may be used to support
          it, such as installer source files

  -h, --help
          Print help (see a summary with '-h')

GLOBAL OPTIONS:
  -v, --verbose
          Whether to output more detailed debug information

      --output-format <OUTPUT_FORMAT>
          The format of the output

          [default: human]

          Possible values:
          - human: Human-readable output
          - json:  Machine-readable JSON output
          

Digging into the argument-parser source code shows a bit of context around the build command.

 /// DO NOT USE: Path to the root dir of the project
 ///
 /// This flag exists for internal testing. It is incorrectly implemented for actual
 /// end-users and will make you very confused and sad.

(I've only tried --project-root but it seems --config-path has the same issues.)

[lynnpepin]

My primary use case is to build an Oranda site into a separate directory, e.g.

cd ~/projects/my_cool_thing_dot_dev/
oranda build --project-root="../my_cool_thing/`

I'm interested in implementing this feature! I dug into the code starting with where Build.run(...) calls Site::build_single(&config, None).write(Some(&config)).

But if I understand the code correctly (and I might not!), it's best not to change the behavior of --project-root to match what the end-user would expect. But implementing a new flag (say, oranda build --source) would mean digging deep into and changing some Axo-specific library code, which I wouldn't expect Axo to accept!

It looks like the intended way-of-doing-things is to build the site alongside the repo and put it in .gitignore, or to point oranda.json to a GitHub project URL.

Am I correct here, or am I being too self-discouraging about contributing? Are there other issues / PRs around this that I might start with?

[shadows-withal]

ah, you're right, I think that bit of the documentation is outdated. it would of course be nice to support an arbitrary source (and destination!) directory, but yeah, that doesn't exist as of right now. if you want to put up a PR removing that bit from the docs that'd be appreciated!

[lynnpepin]

Happy to! I made a PR for the quick change here: #685

[lynnpepin]

oops! forgot to close this after merge