Merge branch 'docs'

Author: giohappy

.readthedocs.yaml

@@ -0,0 +1,22 @@
+# Read the Docs configuration file for MkDocs projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+# Adding the following, ask proposed by readthedocs.io documentation
+# makes the build fail after a while for eccessive memory consumption
+# See https://github.com/readthedocs/readthedocs.org/issues/10585
+build:
+ os: ubuntu-22.04
+ tools:
+   python: "3.10"
+
+mkdocs:
+  configuration: docs/mkdocs.yml
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+  - requirements: docs/requirements.txt

docs/Dockerfile

@@ -0,0 +1,42 @@
+FROM python:3.11-slim
+
+ARG UID=1000
+ARG GID=1000
+ARG USER=dev
+ARG HOME=/home/dev
+ARG APP=/app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      bash ca-certificates \
+      git curl \
+      adduser \
+      libglib2.0-0 \
+        libcairo2 \
+        libpango-1.0-0 \
+        libpangocairo-1.0-0 \
+        libpangoft2-1.0-0 \
+        libgdk-pixbuf-2.0-0 \
+    && rm -rf /var/lib/apt/lists/* \
+    && addgroup --gid "${GID}" "${USER}" \
+    && adduser  --disabled-password --gecos "" \
+                --uid "${UID}" --gid "${GID}" \
+                --home "${HOME}" \
+                "${USER}"
+
+WORKDIR ${APP}
+
+COPY docs/requirements.txt ${APP}/requirements.txt
+COPY mkdocs.yml ${APP}/mkdocs.yml
+COPY pdf_event_hook.py ${APP}/pdf_event_hook.py
+
+RUN python -m venv ${APP}/.venv \
+    && ${APP}/.venv/bin/pip install --upgrade pip wheel setuptools \
+    && ${APP}/.venv/bin/pip install -r ${APP}/requirements.txt
+
+ENV VIRTUAL_ENV=${APP}/.venv
+ENV PATH="${VIRTUAL_ENV}/bin:${PATH}"
+
+RUN chown -R "${UID}:${GID}" "${APP}" "${HOME}"
+
+USER ${USER}
+CMD ["bash"]

docs/LICENSE

@@ -0,0 +1,53 @@
+# GeoNode Documentation
+
+## How to write Documentation
+
+GeoNode uses MarkDown, with [Python Markdown](https://python-markdown.github.io/) support and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) extensions.
+
+### Setup 
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -r requirements.txt
+```
+
+### Develop
+```bash
+mkdocs serve --livereload 
+```
+
+### Build
+```bash
+export ENABLE_PDF_EXPORT=1
+mkdocs build 
+```
+
+## Editing tips
+
+- **Images**:
+  - Can be embedded with `![](img/geo_limits_003.png)`, where the path is relative to the .md page
+  - Can flow on the side of the text by appending the align attriute, for example  `![](img/geo_limits_003.png) { align=left }`
+  - Captions (if needed) can be added with a `\\\ caption \\\` block right below the image. E.g.
+    ```
+    ![](img/geo_limits_003.png)
+    /// caption
+    Image caption
+    ///
+    ```
+- **Links**: Beyond the standard Markdown links, we haveAnchors to headings and other pages is available:
+  - Anchors can be created by placing this `()[]{ #my-anchor }` anywhere, and can be linked from anywhere with `[My anchor][my-anchor]`
+  - Links to other pages can be done by referencing the page name (and optionally the heading) `[project license](about.md#license)`
+- **[Admonition blocks](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#usage)** can be created with:
+  ```
+  !!! Warning
+      The warning text
+  ```
+- **Inline emojis** are supported and their code can be searched with [this tool](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#search).
+- Support for **[content tabs](https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#content-tabs)** is enabled, in case they're useful.
+
+## Reference documentation
+
+  - [MkDocs](https://www.mkdocs.org/)
+  - [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/reference/)
+  - [Python Markdown](https://python-markdown.github.io/)
+

docs/README.md

@@ -0,0 +1,99 @@
+site_name: GeoNode documentation
+repo_name: 'GeoNode/geonode'
+repo_url: https://github.com/GeoNode/geonode/
+use_directory_urls: true
+docs_dir: 'src'
+nav:
+  - Home: index.md
+  - User Guide:
+    - User account: "user-guide/user_account.md"
+    - Catalog Resources: "user-guide/catalog.md"
+    - Datasets:
+      - Upload a dataset: "user-guide/datasets/create.md"
+      - Preview and Styling: "user-guide/datasets/preview.md"
+      - Update and Replace: "user-guide/datasets/update_replace.md"
+      - Remote datasets: "user-guide/datasets/remote.md"
+      - Create empty dataset: "user-guide/datasets/empty.md"
+    - Sharing: "user-guide/sharing.md"
+    - Metadata: "user-guide/metadata.md"
+  - Administration:
+    - Accessing the panel: "admin/panel.md"
+    - Users: "admin/user.md"
+    - Groups: "admin/group.md"
+    - Social Logins: "admin/social.md"
+    - OAuth2: "admin/oauth.md"
+  - Developer Guide: 
+    - API Usage: "development/api.md"
+  - Setup:
+    - Install:
+      - Docker installation:
+            - Prerequisites: setup/docker/prerequisites.md
+            - Vanilla Docker installation: setup/docker/vanilla-docker-installation.md
+            - GeoNode project Docker installation: setup/docker/project-docker-installation.md
+      - Bare installation:
+            - Prerequisites: setup/bare/prerequisites.md
+            - Vanilla bare installation: setup/bare/vanilla-bare-installation.md
+            - GeoNode project bare installation: setup/bare/project-bare-installation.md
+    - Configuration:
+      - Settings: setup/configuration/settings.md
+      - Environmental Variables: setup/configuration/environmental_variables.md
+  - Miscellaneous:
+    - Thesauri: "miscellaneous/thesauri.md"
+    - Backup And Restore: "miscellaneous/br.md"
+
+extra_css:
+  - theme/css/extra.css
+
+extra_javascript:
+  - theme/js/dl-anchors.js
+
+theme:
+  name: material
+  logo: theme/img/geonode-logo-white.svg
+  favicon: theme/img/favicon.ico
+  custom_dir: 'src/theme'
+  language: 'en'
+  features:
+    - header.autohide
+    - navigation.instant
+    - navigation.top
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.path
+    - navigation.indexes
+    - content.code.copy
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.blocks.caption
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - attr_list
+  - def_list
+  - toc:
+      permalink: true
+    
+plugins:
+  - with-pdf: # https://pypi.org/project/mkdocs-with-pdf/
+      author: GeoSolutions Group
+      copyright: 'OsGeo ©'
+      #
+      #cover: false
+      #back_cover: true
+      cover_logo: 'theme/geonode.png'
+      cover_title: GeoNode Documentation
+      cover_subtitle: User Guide and Developer Guide
+      toc_level: 3
+      output_path: pdf/geonode_documentation.pdf
+      enabled_if_env: ENABLE_PDF_EXPORT
+      debug_html: false # set to true to log the html content of the pdf on the console on build
+      show_anchors: true
+      verbose: false    # set to true to log the pdf generation steps in detail
+      custom_template_path: 'src/print_template' # includes custom styles.scss for pdf
+  - search
+  - autorefs

docs/mkdocs.yml

@@ -0,0 +1,40 @@
+# It is for mkdocs-with-pdf plugin 
+# this file is resplosible for rendering the export pdf icon in case ENABLE_EXPORT_PDF = 1 in build environment
+
+import logging
+
+from bs4 import BeautifulSoup
+from mkdocs.structure.pages import Page
+
+
+def inject_link(html: str, href: str,
+                page: Page, logger: logging) -> str:
+    """Adding PDF View button on navigation bar(using material theme)"""
+    def _icon_tag():
+        return BeautifulSoup('<span class="pdf-icon"></span>', 'html.parser')
+
+    logger.info(f'(hook on inject_link: {page.title})')
+    soup = BeautifulSoup(html, 'html.parser')
+    # you can change the icon location by specify the class name of the dom element that you want to append to
+    # Find the DOM element with class "export-pdf-li"
+    export_pdf = soup.find(class_='export-pdf-li')
+    nav = soup.find(class_='md-header-nav')
+    if export_pdf:
+        a = soup.new_tag('a', href=href, title='PDF', target="_blank", **{'class': 'md-tabs__link'})
+        # Append an img tag with a local image source
+        a.append(_icon_tag())
+        a.append("Export PDF")
+        export_pdf.append(a)
+        return str(soup)
+    else:
+          if not nav:
+            # after 7.x
+                nav = soup.find('nav', class_='md-header__inner')
+          if nav:
+                a = soup.new_tag('a', href=href, title='PDF', target="_blank", **{'class': 'md-header__button md-header-nav__button md-icon'})
+                a.append(_icon_tag())
+                a.append("Export PDF")
+                nav.append(a)
+                return str(soup)
+
+    return html

docs/pdf_event_hook.py

@@ -0,0 +1,5 @@
+bs4==0.0.2
+mkdocs==1.6.1
+mkdocs-material==9.7.0
+mkdocs-with-pdf==0.9.3
+mkdocs-autorefs==1.4.4