Project

General

Profile

Actions

Feature #21504

closed

arv-mount reference page

Added by Brett Smith 9 months ago. Updated 7 months ago.

Status:
Resolved
Priority:
Normal
Assigned To:
Category:
Documentation
Story points:
1.0
Release relationship:
Auto

Description

For as much as our users use it, arv-mount is underdocumented. Basically the only resource dedicated to it is the tutorial page about it. Explaining a lot of the more advanced features and options there would be premature, because this first section of the tutorial is about data management, so details of the Arvados API haven't been introduced yet.

Write a new reference-level page with details about arv-mount options. It should cover every arv-mount option in a table, with details about the expected format, how the value is interpreted, and the default (if any). Try to group related options together, like "what gets mounted" options, cache options, log options, etc. Take inspiration from our API reference.

Where should this page live?

  • One option is to add it to a new "Reference" section at the end of the user guide. Long-term we could probably split out a whole "User Reference" supersection out of the user guide, but until we have enough pages to justify that, this is a reasonable starting point.
  • Another option would be to create a section for arv-mount under the SDK section. The obvious downside of this is arv-mount isn't really an SDK, so that's weird. But this section already has other reference material interesting to users (like the Python and CLI SDK references) so it keeps like pages together.

Neither of these options are perfect, but they're both decent short-term solutions without doing damage to the current documentation organization.


Subtasks 1 (0 open1 closed)

Task #21514: Review 21504-arv-mount-referenceResolvedBrett Smith03/05/2024Actions

Related issues

Related to Arvados - Idea #19939: Fully document, illustrate how to use arv-mount --execResolvedBrett SmithActions
Actions #1

Updated by Peter Amstutz 9 months ago

  • Target version changed from To be scheduled to Development 2024-02-28 sprint
Actions #2

Updated by Brett Smith 9 months ago

Draft text for a --filters option, since I just implemented it in #21452 and it's fresh in my head:

--filters: Add arbitrary filters to limit which Arvados objects are accessible from this mount. Write filters in JSON format, using the same qualified field syntax as the groups/contents API method [link]. You can provide the filter list either as a single JSON string on the command line, or as a path to a file with JSON to read.

Note that filters may not be consistently applied to objects you create via the mount.

Example value: Exclude all intermediate workflow outputs, log collections, and filter groups from this mount.

--filters='[["collections.properties.type", "not in", ["intermediate", "log"]], ["groups.class", "!=", "filter"]]'

Example value: Read and apply filters from the file at /etc/arvados/mount-filters.json.

--filters=/etc/arvados/mount-filters.json
Actions #3

Updated by Peter Amstutz 9 months ago

  • Assigned To set to Brett Smith
Actions #4

Updated by Brett Smith 8 months ago

21504-arv-mount-reference @ e0724a24547a1e22377a4ec2fa077b7c3597dbfd - developer-run-tests: #4057

As a practical matter, I was always going to start writing the documentation by copying and pasting the output from arv-mount --help. So, I started by improving that output, making it more organized and consistent.

This branch adds a dedicated FUSE section to the SDK section. I think we should aim towards making the "SDK" section more of a "User Reference" section. It could cover both language SDKs and command line tools. We already do some of this. Note that we already had a page about installing arv-mount here, so this is just expanding that. More thorough reorganization can happen as part of/after #16055.

  • All agreed upon points are implemented / addressed.
    • Yes
  • Anything not implemented (discovered or discussed during work) has a follow-up story.
    • N/A
  • Code is tested and passing, both automated and manual, what manual testing was done is described
    • See above
  • Documentation has been updated.
    • That's all this branch does
  • Behaves appropriately at the intended scale (describe intended scale).
    • No change in scale
  • Considered backwards and forwards compatibility issues between client and server.
    • No change in compatibility
  • Follows our coding standards and GUI style guidelines.
    • Yes
Actions #5

Updated by Peter Amstutz 8 months ago

  • Target version changed from Development 2024-02-28 sprint to Development 2024-03-13 sprint
Actions #6

Updated by Peter Amstutz 8 months ago

  • Target version set to Development 2024-03-13 sprint
  • Tracker changed from Idea to Feature
Actions #7

Updated by Lucas Di Pentima 8 months ago

The documentation updates look very nice, thanks!

I've found a bug in doc/Rakefile, it wasn't possible to just run rake or rake -T to list the available options. This fixed it:

diff --git a/doc/Rakefile b/doc/Rakefile
index 3ec494f57d..f2932284d9 100644
--- a/doc/Rakefile
+++ b/doc/Rakefile
@@ -80,7 +80,7 @@ $build_sdks = begin
       if sdk.can_build?
         sdk
       else
-        puts "Warning: cannot build #{name.replace(/SDK$/, ' SDK')} documentation, skipping".colorize(:light_red)
+        puts "Warning: cannot build #{name.gsub(/SDK$/, ' SDK')} documentation, skipping".colorize(:light_red)
       end
     end
   else
Actions #8

Updated by Brett Smith 8 months ago

  • Status changed from New to Resolved
Actions #9

Updated by Brett Smith 8 months ago

  • Related to Idea #19939: Fully document, illustrate how to use arv-mount --exec added
Actions #10

Updated by Peter Amstutz 7 months ago

  • Release set to 69
Actions

Also available in: Atom PDF