wdl_doc/
config.rs

1//! Configuration type definitions.
2
3use std::path::PathBuf;
4
5use ammonia::Url;
6use wdl_analysis::Config as AnalysisConfig;
7
8/// External URLs related to the project.
9#[derive(Clone, Debug, Default)]
10pub struct ExternalUrls {
11    /// URL pointing to the project's homepage.
12    pub homepage: Option<Url>,
13    /// URL pointing to the project's GitHub repository.
14    pub github: Option<Url>,
15}
16
17/// Additional HTML to embed into each generated page.
18#[derive(Debug, Default)]
19pub struct AdditionalHtml {
20    /// Embed the contents immediately before the closing `</head>` tag.
21    head: Option<String>,
22    /// Embed the contents immediately after the opening `<body>` tag.
23    body_open: Option<String>,
24    /// Embed the contents immediately before the closing `</body>` tag.
25    body_close: Option<String>,
26}
27
28impl AdditionalHtml {
29    /// Create a new [`AdditionalHtml`] struct.
30    pub fn new(
31        head: Option<String>,
32        body_open: Option<String>,
33        body_close: Option<String>,
34    ) -> Self {
35        Self {
36            head,
37            body_open,
38            body_close,
39        }
40    }
41
42    /// Get the HTML to add to the head.
43    pub fn head(&self) -> Option<&str> {
44        self.head.as_deref()
45    }
46
47    /// Get the HTML to add to the body open.
48    pub fn body_open(&self) -> Option<&str> {
49        self.body_open.as_deref()
50    }
51
52    /// Get the HTML to add to the body close.
53    pub fn body_close(&self) -> Option<&str> {
54        self.body_close.as_deref()
55    }
56}
57
58/// Configuration for documentation generation.
59#[derive(Debug)]
60pub struct Config {
61    /// Configuration to use for analysis.
62    pub(crate) analysis_config: AnalysisConfig,
63    /// WDL workspace that should be documented.
64    pub(crate) workspace: PathBuf,
65    /// Output location for the documentation.
66    pub(crate) output_dir: PathBuf,
67    /// An optional markdown file to embed in the root index page.
68    pub(crate) index_page: Option<PathBuf>,
69    /// Initialize pages in light mode instead of the default dark mode.
70    pub(crate) init_light_mode: bool,
71    /// An optional custom theme directory.
72    pub(crate) custom_theme: Option<PathBuf>,
73    /// An optional custom logo to embed in the left sidebar.
74    pub(crate) custom_logo: Option<PathBuf>,
75    /// External URLs related to the project.
76    pub(crate) external_urls: ExternalUrls,
77    /// An optional alternate (light mode) custom logo to embed in the left
78    /// sidebar.
79    pub(crate) alt_logo: Option<PathBuf>,
80    /// Optional HTML to embed in each page.
81    pub(crate) additional_html: AdditionalHtml,
82    /// (**EXPERIMENTAL**) Enable support for documentation comments.
83    pub(crate) enable_doc_comments: bool,
84}
85
86impl Config {
87    /// Create a new documentation configuration.
88    pub fn new(
89        analysis_config: AnalysisConfig,
90        workspace: impl Into<PathBuf>,
91        output_dir: impl Into<PathBuf>,
92    ) -> Self {
93        Self {
94            analysis_config,
95            workspace: workspace.into(),
96            output_dir: output_dir.into(),
97            index_page: None,
98            init_light_mode: false,
99            custom_theme: None,
100            custom_logo: None,
101            external_urls: ExternalUrls::default(),
102            alt_logo: None,
103            additional_html: AdditionalHtml::default(),
104            enable_doc_comments: false,
105        }
106    }
107
108    /// Overwrite the config's index page with the new value.
109    pub fn index_page(mut self, index_page: Option<PathBuf>) -> Self {
110        self.index_page = index_page;
111        self
112    }
113
114    /// Overwrite the config's light mode default with the new value.
115    pub fn init_light_mode(mut self, init_light_mode: bool) -> Self {
116        self.init_light_mode = init_light_mode;
117        self
118    }
119
120    /// Overwrite the config's custom theme with the new value.
121    pub fn custom_theme(mut self, custom_theme: Option<PathBuf>) -> Self {
122        self.custom_theme = custom_theme;
123        self
124    }
125
126    /// Overwrite the config's custom logo with the new value.
127    pub fn custom_logo(mut self, custom_logo: Option<PathBuf>) -> Self {
128        self.custom_logo = custom_logo;
129        self
130    }
131
132    /// Overwrite the config's external URLs with the new value.
133    pub fn external_urls(mut self, external_urls: ExternalUrls) -> Self {
134        self.external_urls = external_urls;
135        self
136    }
137
138    /// Overwrite the config's alternate logo with the new value.
139    pub fn alt_logo(mut self, alt_logo: Option<PathBuf>) -> Self {
140        self.alt_logo = alt_logo;
141        self
142    }
143
144    /// Overwrite the config's additional HTML with the new value.
145    pub fn additional_html(mut self, additional_html: AdditionalHtml) -> Self {
146        self.additional_html = additional_html;
147        self
148    }
149
150    /// Enable support for documentation comments.
151    ///
152    /// NOTE: This is an experimental option, and will be removed in a future
153    /// major release.
154    ///
155    /// For more information, see the pre-RFC discussion
156    /// [here](https://github.com/openwdl/wdl/issues/757).
157    pub fn enable_doc_comments(mut self, enable_doc_comments: bool) -> Self {
158        self.enable_doc_comments = enable_doc_comments;
159        self
160    }
161}
wdl_doc/config.rs

wdl_doc/
config.rs
