Merge pull request #29 from mihaiconstantin/docs/references

Add documentation for Reference Section

NEWS.md

@@ -4,9 +4,19 @@ is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## development
+### Added
+- Add navigation bar and sidebar links under *Reference* for exported package
+  functions and `S3` methods.
+- Enable automatic registration for `.vue` components in
+  `/docs/.vuepress/components/`.
+- Add component `Markdown.vue` for rendering reusable markdown.
+- Add content for functions `powerly`, `validate`, and `generate_model`.
+- Add content for `S3` methods `plot.Method`, `plot.Validation`, and `summary`.
+
 ### Changed
 - Refactor styles and improve readability for narrow screens.
 - Replace incorrect feature image for *Step 1*.
+- Update `CSS` breakpoints for mobile views.
 
 ## 1.8.3 - 2022-08-26
 ### Added

docs/.vuepress/components/Markdown.vue

@@ -0,0 +1,30 @@
+<script>
+import { h } from "vue";
+import markdownIt from "markdown-it";
+
+export default {
+    props: {
+        text: {
+            type: String,
+            required: true
+        }
+    },
+
+    render() {
+        // Create markdown renderer engine.
+        let renderer = new markdownIt({ html: true });
+
+        // Render the component template.
+        return h(
+            "div",
+            {
+                // Add class for our own reference.
+                class: "user-rendered-markdown",
+
+                // Convert the text to markdown.
+                innerHTML: renderer.render(this.text)
+            }
+        );
+    }
+}
+</script>

docs/.vuepress/config.ts

@@ -3,6 +3,11 @@ import { defaultTheme } from "vuepress";
 import { sidebar, navbar, head } from "./configs";
 import { shikiPlugin } from "@vuepress/plugin-shiki";
 import { katexPlugin } from "@renovamen/vuepress-plugin-katex";
+import { getDirname, path } from "@vuepress/utils";
+import { registerComponentsPlugin } from "@vuepress/plugin-register-components";
+
+// Get directory name.
+const __dirname = getDirname(import.meta.url);
 
 /**
  * VuePress config.
@@ -33,6 +38,11 @@ export default defineUserConfig({
         }),
 
         // LaTeX plugin.
-        katexPlugin()
+        katexPlugin(),
+
+        // Register components automatically.
+        registerComponentsPlugin({
+            componentsDir: path.resolve(__dirname, './components')
+        })
     ]
 })

docs/.vuepress/configs/navbar.ts

@@ -7,11 +7,52 @@ import type { NavbarConfig } from '@vuepress/theme-default';
 export const navbar: NavbarConfig = [
     {
         text: "Tutorials",
-        link: "/tutorial/"
+        link: "/tutorial/",
     },
     {
         text: "Reference",
-        link: "/reference/"
+        children: [
+            {
+                text: "Functions",
+                children: [
+                    {
+                        text: "generate_model",
+                        link: "/reference/function/generate-model.md",
+                        activeMatch: 'function/generate-model.*$',
+                    },
+                    {
+                        text: "powerly",
+                        link: "/reference/function/powerly.md",
+                        activeMatch: 'function/powerly.*$',
+                    },
+                    {
+                        text: "validate",
+                        link: "/reference/function/validate.md",
+                        activeMatch: 'function/validate.*$',
+                    }
+                ]
+            },
+            {
+                text: "Methods",
+                children: [
+                    {
+                        text: "plot.Method",
+                        link: "/reference/method/plot-method.md",
+                        activeMatch: 'method/plot-method.*$'
+                    },
+                    {
+                        text: "plot.Validation",
+                        link: "/reference/method/plot-validation.md",
+                        activeMatch: 'method/plot-validation.*$'
+                    },
+                    {
+                        text: "summary",
+                        link: "/reference/method/summary.md",
+                        activeMatch: 'method/summary.*$'
+                    }
+                ]
+            }
+        ]
     },
     {
         text: "Publications",

docs/.vuepress/configs/sidebar.ts

@@ -28,7 +28,46 @@ export const sidebar: SidebarConfig = {
         },
     ],
     "/reference/": [
-        "/reference/index.md",
+        {
+            text: "Reference",
+            link: "/reference/index.md"
+        },
+        {
+            text: 'Functions',
+            collapsible: false,
+            children: [
+                {
+                    text: "generate_model",
+                    link: "/reference/function/generate-model.md"
+                },
+                {
+                    text: "powerly",
+                    link: "/reference/function/powerly.md"
+                },
+                {
+                    text: "validate",
+                    link: "/reference/function/validate.md"
+                }
+            ]
+        },
+        {
+            text: 'Methods',
+            collapsible: true,
+            children: [
+                {
+                    text: "plot.Method",
+                    link: "/reference/method/plot-method.md"
+                },
+                {
+                    text: "plot.Validation",
+                    link: "/reference/method/plot-validation.md"
+                },
+                {
+                    text: "summary",
+                    link: "/reference/method/summary.md"
+                }
+            ]
+        }
     ],
     "/publication/": [
         "/publication/index.md",

docs/.vuepress/styles/general.scss

@@ -8,6 +8,14 @@ table {
     font-size: 0.875rem;
 }
 
+// Code highlighting in lists.
+li {
+    a > code {
+        color: var(--c-text-accent);
+        font-weight: 600;
+    }
+}
+
 // Image zooming overrides.
 .medium-zoom-image, video {
     border-radius: 0.5rem;

docs/.vuepress/styles/index.scss

@@ -5,3 +5,4 @@
 // Imports specific to pages.
 @import "pages/home";
 @import "pages/tutorial";
+@import "pages/reference";

docs/.vuepress/styles/mixins.scss

@@ -10,3 +10,20 @@
 @mixin material_shadow_lg {
 	box-shadow: 0 14px 28px rgba(0, 0, 0, 0.25), 0 10px 10px rgba(0, 0, 0, 0.22);
 }
+
+@mixin table_sm {
+    table {
+        td {
+            line-height: 1.7;
+
+            a > code {
+                color: var(--c-text-accent);
+                font-weight: 600;
+            }
+        }
+
+        @media only screen and (max-width: 419px), (max-width: 428px), (max-width: 517px) {
+            font-size: 0.8rem;
+        }
+    }
+}

docs/.vuepress/styles/pages/reference.scss

@@ -0,0 +1,23 @@
+// Tutorial page styles.
+
+// Imports.
+@import "../mixins";
+
+// Tutorial page container.
+.theme-container.page-reference {
+    @include table_sm;
+
+
+    .showcase-image {
+        p {
+            font-weight: bold;
+        }
+
+        // Adjustments for screens larger than 959px.
+        @media only screen and (min-width: 959px) {
+            img {
+                width: 90%;
+            }
+        }
+    }
+}

docs/.vuepress/styles/pages/tutorial.scss

@@ -5,16 +5,7 @@
 
 // Tutorial page container.
 .theme-container.page-tutorial {
-    table {
-        td {
-            line-height: 1.7;
-
-            a > code {
-                color: var(--c-text-accent);
-                font-weight: 600;
-            }
-        }
-    }
+    @include table_sm;
 
     ol {
         li {
@@ -43,8 +34,6 @@
             // Adjustments for screens smaller than 419px.
             // Additional break points are used based on the content.
             @media only screen and (max-width: 419px), (max-width: 428px), (max-width: 517px) {
-                font-size: 0.8rem;
-
                 td, th {
                     &:nth-child(3) {
                         display: none;

docs/reference/function/generate-model.md

@@ -0,0 +1,103 @@
+---
+pageClass: page-reference
+---
+
+# Generate True Model Parameters
+
+## Description
+
+Generate matrices of true model parameters for the supported true models. These
+matrices are intended to passed to the `model_matrix` argument of the
+[`powerly`](/reference/function/powerly) function.
+
+## Usage
+
+```r:no-line-numbers
+generate_model(type, ...)
+```
+
+## Arguments
+
+|  Name  | Description                                                                                                                                                                                                  |
+| :----: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type` | Character string representing the type of true model. See the [**_True Models_**](/reference/function/generate-model.md#true-models) section for possible values.                                            |
+| `...`  | Required arguments used for the generation of the true model. See the [**_True Models_**](/reference/function/generate-model.md#true-models) section for the arguments required for each type of true model. |
+
+## Return
+
+A matrix containing the model parameters.
+
+## True Models
+
+### Gaussian Graphical Model
+
+**Type:** `ggm`
+
+**`...` arguments:**
+
+|    Name    | Description                                                                                                                                             |
+| :--------: | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
+|  `nodes`   | A single positive integer representing the number of nodes in the network (e.g., `10`).                                                                 |
+| `density`  | A single numerical value indicating the density of the network (e.g., `0.4`).                                                                           |
+| `positive` | A single numerical value representing the proportion of positive edges in the network (e.g., `0.9` for $90\%$ positive edges).                          |
+|  `range`   | A length two numerical value indicating the uniform interval from where to sample values for the partial correlations coefficients (e.g., `c(0.5, 1)`). |
+| `constant` | A single numerical value representing the constant described by [Yin and Li (2011)](https://doi.org/10.1214%2F11-AOAS494).                              |
+
+_**Note.** For more information see the arguments of the
+[`genGGM`](https://rdrr.io/cran/bootnet/man/genGGM.html) function in the
+[`bootnet`](https://CRAN.R-project.org/package=bootnet) package._
+
+**Compatible performance measures:**
+
+- `sen` (sensitivity)
+- `spe` (specificity)
+- `mcc` (Matthews correlation)
+- `rho` (Pearson correlation)
+
+See the [**_Performance
+Measures_**](/reference/function/powerly.md#performance-measures) section for
+the [`powerly`](/reference/function/powerly) function for more information on
+the compatible performance measures.
+
+**Examples**
+
+The example below shows how to generate a true network model based on a random
+architecture ([Barabási & Albert,
+1999](https://doi.org/10.1126/science.286.5439.509)) with $10$ nodes, $90\%$
+positive edge weights, and an edge density of $0.4$.
+
+```r
+# Generate true model.
+true_model <- generate_model(
+    type = "ggm",
+    nodes = 10,
+    density = 0.4,
+    positive = 0.9
+)
+
+# Load the `qgraph` package.
+library(qgraph)
+
+# Plot the model.
+qgraph(true_model)
+```
+
+## See Also
+
+Functions [`powerly`](/reference/function/powerly) and
+[`validate`](/reference/function/validate).
+
+## References
+
+<div class="references">
+
+Barabási, A.-L., & Albert, R. (1999). Emergence of Scaling in Random Networks.
+*Science*, 286(5439), 509–512.
+[https://doi.org/10.1126/science.286.5439.509](https://doi.org/10.1126/science.286.5439.509)
+
+
+Yin, J., & Li, H. (2011). A sparse conditional Gaussian graphical model for
+analysis of genetical genomics data. *The Annals of Applied Statistics*, 5(4),
+2630–2650. [https://doi.org/10.1214/11-AOAS494](https://doi.org/10.1214/11-AOAS494)
+
+</div>