Merge pull request #132 from hmakelin/fix-docs-dead-links

Fix dead links in documentation

README.md

@@ -23,9 +23,9 @@ You will need to have the [Docker Compose plugin][2] and [NVIDIA Container Toolk
 
 ## Install GISNav CLI
 
-The GISNav CLI (`gnc`) is a Docker Compose wrapper that significantly simplifies building and deploying GISNav's Docker Compose services.
+The GISNav CLI (`gnc`) is a Docker Compose wrapper that significantly simplifies building and deploying GISNav's Docker Compose services. It is packaged as a Debian distributable.
 
-Create the Debian package yourself and install `gnc` from it using the following commands:
+Create the Debian distributable and install `gnc` from it using the following commands:
 
 ```bash
 git clone https://github.com/hmakelin/gisnav.git
@@ -80,7 +80,7 @@ listener sensor_gps
 ```
 
 > **Note**
-> The `gisnav` service will by default will send uORB messages to PX4 via the
+> The `gisnav` service will by default send uORB messages to PX4 via the
 > micro-ROS agent which bypasses the GPS driver so you will not see the GPS
 > status with commands like `gps status`.
 
@@ -97,7 +97,7 @@ gnc stop
 # Documentation
 
 See the [latest developer documentation][6] for information on how to setup a local environment for GISNav development,
-for code examples and API documentation, and for contribution guidelines.
+for code examples and API documentation, and integration examples.
 
 [6]: https://hmakelin.github.io/gisnav
 

debian/gisnav/Makefile

@@ -78,11 +78,15 @@ $(BUILD_DIR)/etc/systemd:
 	@mkdir -p $@
 	@cp -r etc/systemd/ $@
 
+# We need to copy .git to make git describe work for the docs (docs are built
+# with git version string). pre-commit might also need the .git folder.
+# TODO: only copy over a shallow copy of git repo  - we do not need entire history
+# nor all branches
 $(BUILD_DIR)/etc/gisnav: $(BUILD_DIR)/etc/gisnav/ros $(BUILD_DIR)/etc/gisnav/docker $(BUILD_DIR)/etc/gisnav/docs
 	@dest=debian/gisnav/$@ && \
 	mkdir -p $@ && \
 	touch $(BUILD_DIR)/COLCON_IGNORE && \
-	cd ${REPO_ROOT_PATH}; rsync -av --exclude-from='.gitignore' Makefile .pre-commit-config.yaml LICENSE.md README.md pyproject.toml $$dest
+	cd ${REPO_ROOT_PATH}; rsync -av --exclude-from='.gitignore' Makefile .pre-commit-config.yaml LICENSE.md README.md pyproject.toml .git $$dest
 
 $(BUILD_DIR)/etc/gisnav/ros:
 	@dest=debian/gisnav/$@ && \
@@ -97,8 +101,8 @@ $(BUILD_DIR)/etc/gisnav/docker:
 	cd ${REPO_ROOT_PATH}; rsync -av --exclude-from='.gitignore' docker/ $$dest
 	@echo -e "\033[1;33;40mWarning! Check the file list above that no unintended files were copied over to the distributable.\033[0m"
 
-# TODO package.json needed for gisnav image build to go through - try to
-# refactor it out (need better defined gisnav image)
 $(BUILD_DIR)/etc/gisnav/docs:
-	@mkdir -p $@/vitepress
-	@echo "{}" > $@/vitepress/package.json
+	@dest=debian/gisnav/$@ && \
+	mkdir -p $@ && \
+	touch $(BUILD_DIR)/COLCON_IGNORE && \
+	cd ${REPO_ROOT_PATH}; rsync -av --exclude-from='.gitignore' docs/ $$dest

docker/mavros/Dockerfile

@@ -129,7 +129,9 @@ RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | b
 
 COPY Makefile .pre-commit-config.yaml LICENSE.md README.md pyproject.toml /opt/colcon_ws/src/gisnav/
 
-# .git needed to make pre-commit work -> initialize a blank repo
-RUN git init
+# .git needed to make pre-commit and git describe work
+# TODO: solve this in a better way - we have an unnecessarily large git
+#  history in the container
+COPY .git /opt/colcon_ws/src/gisnav/.git
 
 ENTRYPOINT ["/entrypoint.sh"]

docs/vitepress/docs/.vitepress/config.mts

@@ -71,6 +71,7 @@ export default withMermaid({
             { text: 'GISNode', link: '/reference/public/gis_node' },
             { text: 'StereoNode', link: '/reference/public/stereo_node' },
             { text: 'PoseNode', link: '/reference/public/pose_node' },
+            { text: 'TwistNode', link: '/reference/public/twist_node' },
           ]
         },
         {

docs/vitepress/docs/deploy-with-docker-compose.md

@@ -37,7 +37,7 @@ The interdependencies between different services are hard-coded into the Docker
 
 ### Mock GPS demo
 
-To deploy the [mock GPS demonstration](/README) introduced locally without using the Makefile, follow the below steps to create, start, and shutdown the required containers. These steps simply repeat what the `demo` Makefile recipe would do.
+To deploy the [mock GPS demonstration](/sitl-local) introduced locally without using the Makefile, follow the below steps to create, start, and shutdown the required containers. These steps simply repeat what the `demo` Makefile recipe would do.
 
 #### Build images
 

docs/vitepress/docs/install-locally.md

@@ -100,7 +100,7 @@ as the workspace might not play nicely with the virtual environment.
 
 GISNav's Python dependencies are divided into [core](./glossary#core-core-functionality), [extended](./glossary#extension-extended-functionality), and development dependencies. You must at least install the core dependencies.
 
-- If you know you are not going to use a specific extension such as `NMEANode`, you can skip installing the corresponding Python [extra](/glossary#extra). `NMEANode` is required for the [mock GPS demo](/README) and enables downstream integration of GISNav as a secondary GPS device via the NMEA protocol.
+- If you know you are not going to use a specific extension such as `NMEANode`, you can skip installing the corresponding Python [extra](/glossary#extra). `NMEANode` is required for the [mock GPS demo](/sitl-local) and enables downstream integration of GISNav as a secondary GPS device via the NMEA protocol.
 
 - The development dependencies are required for various development tasks such as generating documentation and running tests. You do not need to install them if you do not plan to do any development work on GISNav.
 

docs/vitepress/docs/setup-gis-server.md

@@ -1,6 +1,6 @@
 # Setup GIS Server
 
-GISNav uses an onboard GIS server as a source for high-resolution orthoimagery and digital elevation models (DEM) for the approximate global position of the vehicle. This page describes how to setup a self-hosted GIS server. If you are [running the mock GPS demo](/README), you can
+GISNav uses an onboard GIS server as a source for high-resolution orthoimagery and digital elevation models (DEM) for the approximate global position of the vehicle. This page describes how to setup a self-hosted GIS server. If you are [running the mock GPS demo](/sitl-local), you can
 simply use the provided `mapserver` [Docker Compose service](/deploy-with-docker-compose).
 
 ## Overview
@@ -12,7 +12,7 @@ The DEM is optionally used to input ground elevation z-coordinates to the Perspe
 
 You should probably self-host an onboard GIS server with public domain orthoimagery because in a realistic scenario, the GIS should be embedded onboard and not depend on an internet connection. For development, it may sometimes be more convenient to proxy an existing commercial tile-based endpoint.
 
-Because the [mock GPS demo](/README) uses NAIP imagery, in this section we will briefly describe how to obtain NAIP data in case you want to build your own GIS service.
+Because the [mock GPS demo](/sitl-local) uses NAIP imagery, in this section we will briefly describe how to obtain NAIP data in case you want to build your own GIS service.
 
 ::: info Tile-based endpoints
 Commercial web-based map services are often [tile-based](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames) because it is more efficient to serve pre-rendered tiles than to render unique rasters for each individual requested bounding box. You will need a WMS proxy if you decide to go with a tile-based endpoint.