From 8ae13496dae414ca996110bce641e654dadf1820 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Dukai?= Date: Fri, 20 Sep 2024 17:46:45 +0200 Subject: [PATCH] Document API --- .github/workflows/package-release.yaml | 2 +- docs/api.md | 67 +++++++++++++++++++++++++- docs/examples.md | 60 ----------------------- docs/getting-started.md | 50 ++++++++++++------- mkdocs.yml | 2 +- 5 files changed, 100 insertions(+), 81 deletions(-) delete mode 100644 docs/examples.md diff --git a/.github/workflows/package-release.yaml b/.github/workflows/package-release.yaml index 14527e4..d5c7684 100644 --- a/.github/workflows/package-release.yaml +++ b/.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/* diff --git a/docs/api.md b/docs/api.md index 828a8ed..f265067 100644 --- a/docs/api.md +++ b/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 + + 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}//`. + + ```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}") + ``` \ No newline at end of file diff --git a/docs/examples.md b/docs/examples.md deleted file mode 100644 index 3b498c8..0000000 --- a/docs/examples.md +++ /dev/null @@ -1,60 +0,0 @@ -# Examples - -!!! warning "Incomplete section" - -Initialising an empty repository, adding a case, adding a remote and uploading the repository to the remote. - -```shell -cd my-project -geodepot init -geodepot add case-name /path/to/dir/with/data --description "text" -geodepot remote add remote-name https://remote.url -geodepot push remote-name -``` - -Cloning an existing repository from a remote and list the available cases. -Cloning the repository only downloads the index, but not the data files. - -```shell -cd my-project -geodepot init https://remote.url -geodepot list -``` - -Returns: - -```shell -ID NAME DESCRIPTION --- ---- ----------- -1 case-1 A single building in the Netherlands. -``` - -Show the details of a case to see its data files. - -```shell -geodepot show case-1 -``` - -Returns: - -```shell -CASE ID: 1 - -FILE CRS ----- --- -footprint.gpkg EPSG:28992 -pointcloud.laz EPSG:7415 - -``` - -Get the path to the specified file of the specified case. - -```shell -geodepot get case-1 footprint.gpkg -``` - -Returns: - -```shell -/path/to/.geodepot/cases/1/footprint.gpkg -``` diff --git a/docs/getting-started.md b/docs/getting-started.md index f6af7a0..138832f 100644 --- a/docs/getting-started.md +++ b/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/geodepot-api@1.0.4") + ``` === "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 diff --git a/mkdocs.yml b/mkdocs.yml index 7affd90..7985a6b 100644 --- a/mkdocs.yml +++ b/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