Repository navigation
🔧 Refactor examples for more clarity #102
Description
Summary
To enhance the accessibility of the example files in our documentation folder, we should refactor them.
The current approach, which utilizes a comment marker to distinguish between basic and advanced examples within a single file, has proven to be somewhat unclear.
Proposed Changes:
- Split the Existing Example Files: Divide the current example files into two separate files:
xxx_basic.py: This file will contain the basic usage example.xxx_advanced.py: This file will focus on more complex scenarios.
The primary goal of this refactoring is to make the example files less confusing when viewed in isolation. By creating distinct files for basic and advanced examples, we aim to facilitate a better understanding and improve the overall user experience.
Activity
ArBridgeman commentedon Mar 4, 2025
As discussed 2025-03-04 with Mikhail, it would be better if instead of advanced vs basic example usage if we were able to highlight the high-level, preferred way vs lower-level (still supported/valid options). The code and examples within
exasol/bucketfs/_path.pyanddoc/examples/path_like.pyrepresent the ideal, high-level usage. Some of the lower-level code examples would still work (some only for "on-premises"), but they would ideally be distinguished in such a way as to prioritize the Path-like way. [The are 3 use cases: mounted, SAAS, & "on-premises".]