Skip to content

Conversation

@ianthomas23
Copy link
Collaborator

This is the start of the comprehensive documentation and test suite for all cp, get and put functionality. I'll post a link to the docs when they have been built.

I have only considered four of the cp scenarios so far, so we can check if this is the right approach before I complete it. I have made a number of decisions about the docs to obtain something that I am reasonably happy with, but all decisions are open to discussion and changing.

The new docs page described the "expected behavior" idea and is divided up into a number of discrete scenarios, e.g. copy single file to existing directory. Each scenario is in a dropdown so that they can be individually expanded; without this the page will end up too long (so could be split into multiple pages maybe). For the dropdown functionality I've added a new docs dependency on sphinx-design (https://sphinx-design.readthedocs.io/en/latest/tabs.html) which I am familiar with as it is used in Bokeh. I am displaying file trees in sphinx "literal" blocks using a monospace font and some unicode characters as this doesn't add any new dependencies and looks okay. We could make this look much better but I am not sure if it is worth the effort (and future maintenance).

The new 4 tests are not ideal as there is a lot of duplication in the setup code. I'll think about we can replace this with a simple one-off setup of the source directory which can be reused across multiple tests as the tests do not change the source directory only the target one.

@ianthomas23 ianthomas23 force-pushed the copying_docs_and_tests branch from 5b6b290 to 8af099e Compare March 29, 2023 14:34
@ianthomas23
Copy link
Collaborator Author

@martindurant
Copy link
Member

I love the description of expectations, it's long overdue that we have something like this.
Is this PR as far as you want to push the prose? I'm happy to have it go in whenever you say. For some reason, CI seems to have run and passed, but still shows up as "queued" for each run.

@ianthomas23
Copy link
Collaborator Author

I am happy for this to go in as it is. I'll add to it again in future PRs, updating both the docs and the tests at the same time to keep them in sync.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants