MkDocs Documentation (#1)

* Build: add packages for creating project documentation in MkDocs

* Docs: update the wording of the one-line package description

* Docs(mkdocs): create a basic website configuration

* Docs(mkdocs): add repo URLs, icons, copyright etc

* Docs(mkdocs): enable `mkdocstrings` plugin with NumPy-style support

* Docs(mkdocs): arrange sections in logical groups in `mkdocs.yml`

* Docs(mkdocs): separate installation and use into stand-alone pages

* Docs(mkdocs): enable code content copy

* Docs(mkdocs): add a markdown extension to highlight code blocks

* Docs(reference): add a reference page for public package functions

* Docs(usage): add recommended and advanced sections

* Docs(readme): update basic usage in line with the documentation

* Docs(components): add module and function docstrings

* Docs(preview): add a gif preview and a link to the app

* Style(docs): add custom styles for `mkdocs`

* Style(preview): add a border around the preview image

README.md

@@ -6,6 +6,8 @@
 
 A utility package that styles Streamlit apps according to [UNDP Design System](https://design.undp.org).
 
+<img src= "docs/assets/images/preview.gif" alt="App Preview" style="border: 1px solid grey;">
+
 ## Table of Contents
 
 - [Installation](#installation)
@@ -49,12 +51,12 @@ This will edit the theme section in the file if it exists or create it if it doe
 Then, call `apply_style` function inside your application entry point, typically `app.py`: 
 
 ```python
-# app.py or an equivalent module
-import streamlit as st
 import st_undp
+import streamlit as st
 
 st_undp.apply_style()
-st.header("Hello world!")  # now UNDP-styled
+
+st.title("Hello world!")  # now UNDP-styled
 ```
 
 ## Features

docs/index.md

@@ -0,0 +1,9 @@
+# Welcome to st-undp
+
+A utility package that helps build Streamlit apps in line with [UNDP Design System](https://design.undp.org). Bootstrap
+your app development with `st-undp`! 
+
+Explore this documentation for details on how to use the package or visit [st-undp app](https://st-undp.azurewebsites.net)
+for a live demonstration.
+
+<img src= "./assets/images/preview.gif" alt="App Preview" style="border: 1px solid grey;">

docs/installation.md

@@ -0,0 +1,19 @@
+# Installation
+
+Currently, the package is distributed via GitHub only. You can install it with `pip`:
+
+```bash
+# latest version from the default branch (not recommended)
+pip install git+https://github.com/undp-data/st-undp.git
+
+# specific version from a tagged release (recommended) 
+pip install git+https://github.com/undp-data/[email protected]
+```
+
+You can also add it to your `requirements.txt`:
+
+```requirements
+st-undp @ git+https://github.com/undp-data/[email protected]
+```
+
+See [VCS Support](https://pip.pypa.io/en/stable/topics/vcs-support/#vcs-support) for more details.

docs/reference.md

@@ -0,0 +1,3 @@
+# Reference
+
+::: st_undp

docs/stylesheets/extra.css

@@ -0,0 +1,54 @@
+@font-face {
+    font-family: "proxima-nova";
+    src: url("https://use.typekit.net/af/705e94/00000000000000003b9b3062/27/l?primer=7cdcb44be4a7db8877ffa5c0007b8dd865b3bbc383831fe2ea177f62257a9191&fvd=n4&v=3") format("woff2"), url("https://use.typekit.net/af/705e94/00000000000000003b9b3062/27/d?primer=7cdcb44be4a7db8877ffa5c0007b8dd865b3bbc383831fe2ea177f62257a9191&fvd=n4&v=3") format("woff"), url("https://use.typekit.net/af/705e94/00000000000000003b9b3062/27/a?primer=7cdcb44be4a7db8877ffa5c0007b8dd865b3bbc383831fe2ea177f62257a9191&fvd=n4&v=3") format("opentype");
+    font-display: auto;
+    font-style: normal;
+    font-weight: 400;
+    font-stretch: normal;
+}
+
+:root {
+    --blue: #006EB5;
+    --white: #FAFAFA;
+    --md-text-font: "proxima-nova";
+    --md-primary-fg-color: var(--white);
+    --md-primary-fg-color--light: var(--white);
+    --md-primary-fg-color--dark: var(--white);
+    --undp-header-height: 5rem;
+}
+
+/* Style the header */
+header {
+    height: var(--undp-header-height);
+}
+
+/* Make the logo larger and reduce margins */
+.md-logo {
+    margin: 0 !important;
+}
+
+.md-logo img {
+    height: var(--undp-header-height) !important;
+}
+
+/* Make the title visible on white background */
+.md-header__title {
+    color: black;
+}
+
+/* Make GitHub details visible on white background */
+.md-header__source {
+    color: black;
+}
+
+/* Fix the text colours if using white as the primary fg */
+
+/* Navigation items */
+.md-nav__item .md-nav__link--active {
+    color: var(--blue);
+}
+
+/* Links */
+.md-typeset a {
+    color: var(--blue);
+}

docs/usage.md

@@ -0,0 +1,190 @@
+# Usage
+
+The package can be used to style your existing Streamlit app with just a couple of lines of code. Alternatively, you
+can use custom components provided by the package to build more advanced applications in line with UNDP Design System.
+
+## Basic Usage
+
+The package is intended to make styling a breeze. The most basic usage involves only two simple steps.
+
+First, use the CLI to set up the recommended theme in `.streamlit/config.toml`:
+
+```shell
+python -m st_undp configure
+```
+
+This will edit the theme section in the file if it exists or create it if it doesn't.
+Then, call `apply_style` function inside your application entry point, typically `app.py`: 
+
+```python hl_lines="4"
+import st_undp
+import streamlit as st
+
+st_undp.apply_style()  # call this before any other streamlit function
+
+st.title("Hello world!")  # now UNDP-styled
+```
+
+Once you apply the style, most streamlit components will be properly styled and work out-of-the box. Note that
+[`st_undp.apply_style`](reference.md/#st_undp.apply_style) calls `st.set_page_config` internally
+and sets the required settings, including the favicon.
+
+## Recommended Usage
+
+In addition to styles, the package provides custom components to help you build even 
+better-looking UNDP-styled apps. Two of these components are strongly recommended for all applications.
+These are the header and the footer.
+
+### Header
+
+Use [`st_undp.header`](reference.md/#st_undp.header) to add the 
+[header component](https://design.undp.org/?path=/story/components-navigation-components-main-navigation-country-header--country-header)
+that includes the official logo.
+
+```python hl_lines="6-10"
+import st_undp
+import streamlit as st
+
+st_undp.apply_style()
+
+st_undp.header(
+    title="Data Futures Exchange",
+    subtitle="st-undp Application",
+    logo="undp",  # set to "pnud" for French/Spanish
+)
+
+st.title("Hello world!")
+```
+
+If you are building a [multipage application](https://docs.streamlit.io/develop/concepts/multipage-apps),
+use the header component to create navigation. Assuming you defined your pages in `pages/` directory,
+use a list of pages to add navigation.
+
+```python hl_lines="6-18 23 29-31"
+import st_undp
+import streamlit as st
+
+st_undp.apply_style()
+
+# define the pages
+pages = [
+    st.Page(
+        page="pages/page1.py",
+        title="first page",
+        url_path="./",  # use this pattern and not the `default` parameter
+    ),
+    st.Page(
+        page="pages/page2.py",
+        title="second page",
+        url_path="/second",
+    ),
+]
+
+st_undp.header(
+    title="Data Futures Exchange",
+    subtitle="st-undp Application",
+    pages=pages,  # pass a list of `st.Page` items to add navigation
+    logo="undp",
+)
+
+st.title("Hello world!")
+
+# run the pages
+pg = st.navigation(pages=pages, position="hidden")  # set position to "hidden"
+pg.run()
+```
+
+### Footer
+
+Add a UNDP-styled footer with [`st_undp.footer`](reference.md/#st_undp.footer). You can choose between the default UNDP footer,
+the footer used by the Data Futures Exchange or create your custom one.
+
+```python hl_lines="8"
+import st_undp
+import streamlit as st
+
+st_undp.apply_style()
+
+st.title("Hello world!")
+
+st_undp.footer("dfx")  # call it at the end of your script
+```
+
+To create a custom footer, pass a dictionary whose values are dictionaries too. The keys of the
+outer dictionary will be used as column names while the keys and values of the inner dictionaries will
+be interpreted as column items and their links respectively. Here is an example:
+
+```python hl_lines="8-21"
+import st_undp
+import streamlit as st
+
+st_undp.apply_style()
+
+st.title("Hello world!")
+
+# custom footer items
+columns = {
+    "focus areas": {
+        "Energy": "https://data.undp.org/energy",
+        "Environment": "https://data.undp.org/environment",
+        "Governance": "https://data.undp.org/governance",
+    },
+    "about us": {
+        "About DFx": "https://data.undp.org/about",
+        "Our Partners": "https://data.undp.org/our-partners",
+        "Contact Us": "https://data.undp.org/contact-us",
+    },
+}
+st_undp.footer(columns)
+```
+
+## Advanced Usage
+
+For even more demanding use cases, you can use additional custom components to create breadcrumbs,
+summaries and various types of cards.
+
+### Stats Card
+
+Use [`st_undp.stats_card`](reference.md/#st_undp.stats_card) to create a [stats card](https://design.undp.org/iframe?viewMode=story&id=components-ui-components-cards-stats-card--stats-card&args=) component.
+
+```python hl_lines="8-12 14-18"
+import st_undp
+import streamlit as st
+
+st_undp.apply_style()
+
+st.title("Hello world!")
+
+st_undp.stats_card(
+    value=3.14,
+    title="Pi",
+    text="The ratio of a circle's circumference to its diameter",
+)
+```
+
+If you have multiple cards, you can easily arrange them in one row with `st.columns`.
+
+```python hl_lines="8 10 17"
+import st_undp
+import streamlit as st
+
+st_undp.apply_style()
+
+st.title("Hello world!")
+
+col1, col2 = st.columns(2)
+
+with col1:
+    st_undp.stats_card(
+        value=3.14,
+        title="Pi",
+        text="The ratio of a circle's circumference to its diameter",
+    )
+
+with col2:
+    st_undp.stats_card(
+        value=2.71,
+        title="Euler's constant",
+        text="The limiting difference between the harmonic series and the natural logarithm",
+    )
+```

mkdocs.yml

@@ -0,0 +1,47 @@
+site_name: st-undp
+site_url: https://undp-data.github.io/st-undp
+
+theme:
+  name: material
+  logo: assets/images/logo.svg
+  favicon: assets/images/favicon.ico
+  icon:
+    repo: material/github
+    edit: material/pencil
+    view: material/eye
+  features:
+    - content.action.view
+    - content.action.edit
+    - content.code.copy
+
+nav:
+  - Home: index.md
+  - Installation: installation.md
+  - Usage: usage.md
+  - Reference: reference.md
+
+plugins:
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            docstring_style: numpy
+
+extra:
+  social:
+    - icon: material/github
+      link: https://github.com/undp-data
+    - icon: material/web
+      link: https://data.undp.org
+
+extra_css:
+  - stylesheets/extra.css
+
+markdown_extensions:
+  - pymdownx.superfences
+
+copyright: Copyright © 2024 United Nations Development Programme
+
+repo_url: https://github.com/undp-data/st-undp
+repo_name: undp-data/st-undp
+edit_uri: edit/main/docs/