Skip to content

Commit

Permalink
Merge pull request #17228 from jmchilton/markdown_help_distinction
Browse files Browse the repository at this point in the history 
Overhaul Galaxy Markdown Help
  • Loading branch information
@martenson
martenson authored Jan 18, 2024
2 parents afd4cca + 50cd3c7 commit 546b994
Show file tree
Hide file tree
Showing 9 changed files with 258 additions and 105 deletions.
23 changes: 23 additions & 0 deletions client/src/components/Markdown/DirectiveHelp.vue
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
<script setup lang="ts">
import { computed } from "vue";
import { directiveEntry } from "./directives";
interface DirectiveHelpProps {
directive: string;
mode: "page" | "report";
}
const props = defineProps<DirectiveHelpProps>();
const entry = computed(() => directiveEntry(props.directive, props.mode));
</script>

<template>
<span>
<dt>
<tt>{{ directive }}</tt>
</dt>
<dd>{{ entry.help }}</dd>
</span>
</template>
17 changes: 17 additions & 0 deletions client/src/components/Markdown/DirectiveHelpSection.vue
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
<script setup lang="ts">
import DirectiveHelp from "./DirectiveHelp.vue";
interface DirectiveHelpSectionProps {
directives: string[];
mode: "page" | "report";
}
defineProps<DirectiveHelpSectionProps>();
</script>

<template>
<dl>
<DirectiveHelp v-for="directive in directives" :key="directive" :directive="directive" :mode="mode">
</DirectiveHelp>
</dl>
</template>
10 changes: 7 additions & 3 deletions client/src/components/Markdown/MarkdownEditor.vue
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@
</div>
</div>
</div>
<MarkdownHelp ref="help" />
<MarkdownHelpModal ref="help" :mode="mode" />
</div>
</template>

Expand All @@ -46,7 +46,7 @@ import FlexPanel from "components/Panels/FlexPanel";
import _ from "underscore";
import Vue from "vue";
import MarkdownHelp from "./MarkdownHelp";
import MarkdownHelpModal from "./MarkdownHelpModal";
import MarkdownToolBox from "./MarkdownToolBox";
Vue.use(BootstrapVue);
Expand All @@ -60,7 +60,7 @@ export default {
MarkdownToolBox,
FlexPanel,
FontAwesomeIcon,
MarkdownHelp,
MarkdownHelpModal,
},
props: {
markdownText: {
Expand All @@ -79,6 +79,10 @@ export default {
type: String,
default: null,
},
mode: {
type: String,
default: "report",
},
},
data() {
return {
Expand Down
201 changes: 126 additions & 75 deletions client/src/components/Markdown/MarkdownHelp.vue
View file
Original file line number Diff line number Diff line change
@@ -1,100 +1,151 @@
<script setup>
import { datasetCommandsHtml, markdownGeneralHelpHtml } from "components/Markdown/help";
import { ref } from "vue";
<script setup lang="ts">
import { computed } from "vue";
const modal = ref(null);
import DirectiveHelpSection from "./DirectiveHelpSection.vue";
function showMarkdownHelp() {
modal.value.show();
interface MarkdownHelpProps {
mode: "report" | "page";
}
defineExpose({
showMarkdownHelp,
});
const props = defineProps<MarkdownHelpProps>();
const page = computed(() => props.mode == "page");
</script>

<template>
<b-modal ref="modal" hide-footer>
<template v-slot:modal-title>
<h2 class="mb-0">Markdown Help</h2>
</template>
<div>
<h3>Overview</h3>
<p>
This Markdown document will be used to generate your Galaxy Page. This document should be Markdown with
embedded commands for extracting and displaying Galaxy objects and their metadata.
</p>

<p v-html="markdownGeneralHelpHtml"></p>

<h3>History Contents Commands</h3>

<p>
These commands reference a dataset. For instance, the following examples would display the dataset
collection corresponding to a Galaxy dataset collection ID and display a single dataset as an image
corresponding to a Galaxy dataset ID.
</p>

<pre>
<div>
<h3>Overview</h3>
<p>
<span v-if="page"> This Markdown document will be used to generate your Galaxy Page. </span>
<span v-else> This Markdown document will be used to generate your workflow invocation report. </span>
This document should be Markdown with embedded commands for extracting and displaying Galaxy objects and/or
their metadata.
</p>

<p>
For an overview of standard Markdown visit the
<a href="https://commonmark.org/help/tutorial/">commonmark.org tutorial</a>.
</p>

<p>
The Galaxy extensions to Markdown are represented as code blocks, these blocks start with the line
<tt>```galaxy</tt> and end with the line <tt>```</tt> and have a command with arguments between these lines.
<span v-if="page">
These arguments reference your Galaxy objects such as datasets, jobs, and workflows.
</span>
<span v-else>
These arguments reference parts of your workflow such as steps, inputs, and outputs by label in the
middle.
</span>
</p>

<h3>History Contents Commands</h3>

<p>
These commands reference a dataset or dataset collection. For instance, the following examples would display
the dataset collection metadata and would embed a dataset into the document as an image.

<span v-if="page">
These elements are referenced by object IDs used by the Galaxy API. The Markdown editor will let you
pick objects graphically but they will be embedded into the Markdown with these IDs.
</span>

<span v-else>
These elements are referenced by input or output labels for the workflow. If a dataset or collection
you'd like to reference is not available for selection in the Markdown editor, be sure to assign a label
to the object in the workflow editor first.
</span>
</p>

<pre v-if="page">
```galaxy
history_dataset_collection_display(history_dataset_collection_id=33b43b4e7093c91f)
```
</pre
>
>
<pre v-else>
```galaxy
history_dataset_collection_display(output=mapped_bams)
```
</pre
>

<pre>
<pre v-if="page">
```galaxy
history_dataset_as_image(history_dataset_id=33b43b4e7093c91f)
```
</pre
>

<p v-html="datasetCommandsHtml"></p>

<h3>Workflow Commands</h3>

<p>
These commands reference a workflow (currently only one). The following example would display a
representation of the workflow in the resulting Galaxy Page:
</p>

<pre>
>
<pre v-else>
```galaxy
history_dataset_as_image(output=normalized_result_plot)
```
</pre
>

<DirectiveHelpSection
:mode="mode"
:directives="[
'history_dataset_display',
'history_dataset_collection_display',
'history_dataset_as_image',
'history_dataset_as_table',
'history_dataset_peek',
'history_dataset_info',
]" />

<h3>Workflow Commands</h3>

<p v-if="page">
These commands reference a workflow by an object ID. The following example would display a representation of
the workflow in the resulting Galaxy Page:
</p>
<p v-else>These commands reference the current workflow and do not require an input for the most part.</p>

<pre v-if="page">
```galaxy
workflow_display(workflow_id=33b43b4e7093c91f>)
```
</pre
>

<dl>
<dt><tt>workflow_display</tt></dt>
<dd>Embed a description of the workflow itself in the resulting document.</dd>
</dl>

<h3>Job Commands</h3>

<p>
These commands reference a Galaxy job.For instance, the following example would show the job parameters
the job ID 33b43b4e7093c91f:
</p>

<pre>
>
<pre v-else>
```galaxy
workflow_display()
```
</pre
>

<DirectiveHelpSection
:mode="mode"
:directives="['workflow_license', 'workflow_display', 'workflow_image', 'invocation_time']" />

<h3>Job Commands</h3>

<p v-if="page">
These commands reference a Galaxy job. For instance, the following example would show the job parameters the
job ID <tt>33b43b4e7093c91f</tt>.
</p>
<p v-else>
These commands reference a Galaxy job or collection of jobs associated with a labeled step in the workflow.
For instance, the following example would show the job parameters for the step with the label
<tt>mapping</tt>.
</p>

<pre v-if="page">
```galaxy
job_parameters(job_id=33b43b4e7093c91f)
```
</pre
>

<dt><tt>tool_stderr</tt></dt>
<dd>Embed the tool standard error stream for this job in the resulting document.</dd>
<dt><tt>tool_stdout</tt></dt>
<dd>Embed the tool standard output stream for this job in the resulting document.</dd>
<dt><tt>job_metrics</tt></dt>
<dd>
Embed the job metrics for this job in the resulting document (if Galaxy is configured and you have
permission).
</dd>
<dt><tt>job_parameters</tt></dt>
<dd>Embed the tool parameters for this job in the resulting document.</dd>
</div>
</b-modal>
>
<pre v-else>
```galaxy
job_parameters(step=mapping)
```
</pre
>

<DirectiveHelpSection
:mode="mode"
:directives="['tool_stderr', 'tool_stdout', 'job_metrics', 'job_parameters']" />
</div>
</template>
37 changes: 37 additions & 0 deletions client/src/components/Markdown/MarkdownHelpModal.vue
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
<script setup lang="ts">
import { computed, ref } from "vue";
import MarkdownHelp from "./MarkdownHelp.vue";
interface MarkdownHelpModalProps {
mode: "report" | "page";
}
const props = defineProps<MarkdownHelpModalProps>();
const show = ref(false);
const title = computed(() => {
if (props.mode == "page") {
return "Markdown Help for Pages";
} else {
return "Markdown Help for Invocation Reports";
}
});
function showMarkdownHelp() {
show.value = true;
}
defineExpose({
showMarkdownHelp,
});
</script>

<template>
<b-modal v-model="show" hide-footer>
<template v-slot:modal-title>
<h2 class="mb-0">{{ title }}</h2>
</template>
<MarkdownHelp :mode="mode" />
</b-modal>
</template>
Loading

0 comments on commit 546b994

Please sign in to comment.