Support for local development

[Compton-US]

While working on the mapping feature branches, I encountered a few issues that aren't really bugs, but dev experience improvements that we might need to consider. It is possible I could have overlooked setting an environment variable to address some of this.

1. When generating documentation, it would be nice if I could just generate it for a single branch of OSCAL.
2. When I am working on a local branch that has not been published, it would be useful to be able to point to the local branch.
3. Optionally, it would be useful to supply the list of branches in the event I have multiple local branches, or published branches that I want to review.

My workaround

In order to accomplish this:

• I edited list_revisions.sh and echoed my own branch names, and commented out the other branches.
• I symlinked support/OSCAL to my local OSCAL repo.
• After working on OSCAL I ran:

  $ make clean 
  $ make site 
  $ make serve
  

• I reviewed documentation for the branches that I listed.

If there is a way to use the environment variables to accomplish this, it might just need to be added to the README. It looks like OSCAL_DIR and REVISIONS would be the ones, but not sure if they truly support being passed from the command line.

[nikitawootten-nist]

Hey Chris, there is actually a simpler way to work around this. Makefile variables can be overridden, so instead of editing list_revisions.sh you can just override the variable its result is stored in:

$ make site REVISIONS="v1.1.0 my-test-branch my-other-test-branch"

This behavior is a bit unexpected. I agree it should be documented somewhere.

[nikitawootten-nist]

As for pointing at alternative OSCAL source repositories, currently you would have to edit the generate_modeldoc.sh script, but the script could be edited to either:

1. Accept an environment variable to override the OSCAL source directory
2. Expect the OSCAL source directory to be passed in as an argument, so that it would also be controlled via the Makefile

The ladder has some interesting properties, such as allowing the Makefile to ensure the user has initialized the submodule (unless it has been overridden).

[Compton-US]

Thanks. I need to make another feature branch this afternoon and start work, so I'll reset and try this out.

[Compton-US]

This approach seems to be working for me. I've adjusted the generate_modeldoc script and Makefile to support the local OSCAL repo part, and I'll push it up as a feature branch sometime today for consideration. I need to add something to the readme on how to use.

[nikitawootten-nist]

This approach seems to be working for me. I've adjusted the generate_modeldoc script and Makefile to support the local OSCAL repo part, and I'll push it up as a feature branch sometime today for consideration. I need to add something to the readme on how to use.

Awesome, if possible I'd like to also amend the script to optionally not use a worktree (just use the provided oscal folder without making a temporary copy)

[iMichaela]

The solution indicated by @nikitawootten-nist needs to be tested and documented in the README with examples of how to:

1. override the REVISION to generate the documentation for a single branch or a selected list of branches (releases or prototypes) 2.
2. pointing at alternative OSCAL source repositories by editing the generate_modeldoc.sh script.

Alternatively, the script can be modified under this issue, to accept an environment variable to override the OSCAL source directory
OR to expect the OSCAL source directory to be passed in as an argument, so that it would also be controlled via the Makefile