Document API

.github/workflows/package-release.yaml

@@ -156,6 +156,6 @@ jobs:
       uses: softprops/action-gh-release@v2
       with:
         prerelease: true
-        repository: 3DGI/geodepot
+        repository: 3DBAG/geodepot
         token: ${{ secrets.GITHUB_TOKEN }}
         files: dist/*

docs/api.md

@@ -1,3 +1,68 @@
 # API Reference
 
-!!! warning "Incomplete section"
+## Init
+
+Initialize a local repository from an existing Geodepot repository.
+The constructor take a path to a local directory or a URL to a remote directory.
+The path must contain a valid Geodepot repository.
+After initialization, the data items in this repository can be downloaded and used in the tests.
+
+=== "C++"
+
+    ``` c++
+    #include <geodepot/geodepot.h>
+
+    int main(void) {
+      auto repo = geodepot::Repository(
+          "https://data.3dgi.xyz/geodepot-test-data/mock_project");
+    }
+    ```
+
+=== "Python"
+
+    ``` python
+    from geodepot import Repository
+
+    def main():
+        repo = Repository("https://data.3dgi.xyz/geodepot-test-data/mock_project")
+    ```
+
+=== "CMake"
+
+    ```cmake
+    include(GeoDepot)
+
+    GeodepotInit("https://data.3dgi.xyz/geodepot-test-data/mock_project")
+    ```
+
+## Get
+
+Once the repository has been initialized, it is possible to get the full local path to a data item.
+If the data is not available locally, it will be downloaded from the remote on the first call if the function.
+
+=== "C++"
+
+    ``` c++
+    std::filesystem::path p = repo.get("wippolder/wippolder.gpkg");
+    ```
+
+=== "Python"
+
+    ``` python
+    p = repo.get("wippolder/wippolder.gpkg")
+    ```
+
+=== "CMake"
+    Geodepot sets the `GEODEPOT_DIR` CMake cache variable to the path to the initialized geodepot repository.
+    In order obtain the full path to a data item, construct the path as `${GEODEPOT_DIR}/<case name>/<data name>`.
+
+    ```cmake
+    GeodepotGet("wippolder/wippolder.gpkg")
+
+    # add executables, entable tests etc...
+
+    add_test(
+          NAME "function-using-geodepot-data"
+          COMMAND test_geodepot_cmake "${GEODEPOT_DIR}/wippolder/wippolder.gpkg"
+          WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}")
+    ```

docs/getting-started.md

@@ -4,40 +4,54 @@
 
 ### Command line tool
 
-!!! warning "Incomplete section"
+Download the precompiled executable from the [latest release](https://github.com/3DBAG/geodepot/releases/latest), uncompress it and run the `geodepot` executable in the `geodepot` directory.
+Note that the `geodepot` executable must remain in the `geodepot` directory, because it uses relative links to it's dependencies.
 
-```shell
-pip install geodepot
-```
+Geodepot has complex dependencies, so do not `pip install` it, unless you are developing Geodepot itself.
+Use the provided binaries instead.
 
 ### API
 
 === "C++"
 
+    If you are using CMake, use `FetchContent` (or [CPM](https://github.com/cpm-cmake/CPM.cmake)) and link against `geodepot`.
+
+    Using CMake's `FetchContent`.
+
+    ```cmake
+    FetchContent_Declare(
+      geodepot-api
+      GIT_REPOSITORY https://github.com/3DBAG/geodepot-api.git
+    )
+    FetchContent_MakeAvailable(geodepot-api)
+
+    add_executable("test_integration" "test_integration.cpp")
+    target_link_libraries("test_integration" geodepot)
+    ```
 
+    Using CPM.
+
+    ```cmake
+    CPMAddPackage("gh:3dbag/[email protected]")
+    ```
 
 === "Python"
 
-    ``` python
-    git clone 
+    Use pip to build the Geodepot API and install the bindings.
+
+    ```shell
+    git clone https://github.com/3DBAG/geodepot-api.git
+    cd geodepot-api
+    pip install .
     ```
 
 === "CMake"
 
+    To add the Geodepot CMake functions to your current project, simply add the latest release of `GeoDepot.cmake` to your project's `cmake` directory, then include it.
+    Make sure you include all modules from the `cmake` directory.
+
     ```cmake
     include(GeoDepot)
-
-    GeodepotInit("https://data.3dgi.xyz/geodepot-test-data/mock_project/.geodepot")
-    GeodepotGet("wippolder/wippolder.gpkg")
-
-    # add executables, entable tests etc...
-
-    # The GEODEPOT_DIR variable stores the path to the data in the repository that was 
-    # initialized and downloaded by GeodepotInit and GeodepotGet
-    add_test(
-          NAME "function-using-geodepot-data"
-          COMMAND test_geodepot_cmake "${GEODEPOT_DIR}/wippolder/wippolder.gpkg"
-          WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}")
     ```
 
 ## First time setup

mkdocs.yml

@@ -23,6 +23,7 @@ theme:
     - navigation.indexes
     - search.highlight
     - search.suggest
+    - content.tabs.link
 markdown_extensions:
   # Python Markdown
   - toc:
@@ -40,4 +41,3 @@ nav:
   - Concepts: concepts.md
   - Commands: cli.md
   - API Reference: api.md
-  - Examples: examples.md