<!-- 
RSS generated by JIRA (1001.0.0-SNAPSHOT#100246-sha1:7a5c50119eb0633d306e14180817ddef5e80c75d) at Thu Feb 08 23:16:14 UTC 2024

It is possible to restrict the fields that are returned in this document by specifying the 'field' parameter in your request.
For example, to request only the issue key and summary add field=key&field=summary to the URL of your request.
-->
<rss version="0.92" >
<channel>
    <title>FOLIO Jira</title>
    <link>https://folio-org.atlassian.net</link>
    <description>This file is an XML representation of an issue</description>
    <language>en-us</language>    <build-info>
        <version>1001.0.0-SNAPSHOT</version>
        <build-number>100246</build-number>
        <build-date>07-02-2024</build-date>
    </build-info>

<item>
            <title>[FOLIO-1833] Spike: Create brief demonstration of RAML ability to use Markdown documentation</title>
                <link>https://folio-org.atlassian.net/browse/FOLIO-1833</link>
                <project id="10290" key="FOLIO">FOLIO</project>
                    <description>&lt;p&gt;The RAML files can utilise multiple &quot;documentation&quot; nodes using content in Markdown format. It can be in-line, or included via separate files located locally to the module&apos;s RAMLs. Some top-level files could also be included from the shared &quot;raml-util&quot; repository.&lt;/p&gt;

&lt;p&gt;Create a basic demonstration.&lt;/p&gt;</description>
                <environment></environment>
        <key id="81015">FOLIO-1833</key>
            <summary>Spike: Create brief demonstration of RAML ability to use Markdown documentation</summary>
                <type id="10003" iconUrl="https://folio-org.atlassian.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10318?size=medium">Task</type>
                                            <priority id="10002" iconUrl="https://dev.folio.org/assets/jira-priority/jira-p3.svg">P3</priority>
                        <status id="6" iconUrl="https://folio-org.atlassian.net/images/icons/statuses/closed.png" description="The issue is considered finished, the resolution is correct. Issues which are closed can be reopened.">Closed</status>
                    <statusCategory id="3" key="done" colorName="green"/>
                                    <resolution id="10003">Done</resolution>
                                                        <assignee accountid="61cd0ca0bce5e00069e98be7">David Crossley</assignee>
                                                                <reporter accountid="61cd0ca0bce5e00069e98be7">David Crossley</reporter>
                                    <labels>
                            <label>platform-backlog</label>
                            <label>raml</label>
                    </labels>
                <created>Thu, 28 Feb 2019 08:56:12 +0000</created>
                <updated>Wed, 3 Jun 2020 16:39:33 +0000</updated>
                            <resolved>Wed, 6 Mar 2019 02:29:47 +0000</resolved>
                                                                        <due></due>
                            <votes>0</votes>
                                    <watches>3</watches>
                                                                <comments>
                                                            <comment id="192230" author="61cd0ca0bce5e00069e98be7" created="Fri, 1 Mar 2019 02:18:46 +0000"  >&lt;p&gt;See the branch &lt;a href=&quot;https://github.com/folio-org/mod-notes/tree/folio-1833-raml-markdown&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;https://github.com/folio-org/mod-notes/tree/folio-1833-raml-markdown&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;The file &apos;mod-notes/ramls/note.raml&apos; has been edited to add more documentation at various levels. Some uses in-line documentation, some are included via separate files.&lt;/p&gt;

&lt;p&gt;The generated output documentation is not processed by Jenkins CI for a branch, only for master. See the locally generated documentation attached to this ticket.&lt;/p&gt;

&lt;p&gt;Each additional documentation snippet is prefixed with text &lt;/p&gt;
&lt;div class=&quot;preformatted panel&quot; style=&quot;border-width: 1px;&quot;&gt;&lt;div class=&quot;preformattedContent panelContent&quot;&gt;
&lt;pre&gt;FOLIO-1833 demo&lt;/pre&gt;
&lt;/div&gt;&lt;/div&gt;
&lt;p&gt; so search input and output for that term.&lt;/p&gt;

&lt;p&gt;The generated output documentation uses &quot;raml2html themes&quot;. The &quot;view-1&quot; uses the default theme. The &quot;view-2&quot; uses the &quot;Plain theme&quot; and we have a fork of that with a couple of basic enhancements. More could be done, plus improved CSS. &lt;/p&gt;

&lt;p&gt;At the top of the RAML file there is &quot;baseUri&quot; and &quot;version&quot;. These nodes are currently under-utilised, and often incorrect and confusing. There are some basic Jira tickets to improve those.&lt;/p&gt;

&lt;p&gt;To tweak the demo checkout the branch, and do local RAML/Schema validation and documentation generation using a local clone of &lt;a href=&quot;https://github.com/folio-org/folio-tools/tree/master/lint-raml&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;lint-raml&lt;/a&gt; and &lt;a href=&quot;https://github.com/folio-org/folio-tools/tree/master/generate-api-docs&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;generate-api-docs&lt;/a&gt;. &lt;/p&gt;</comment>
                                                            <comment id="192231" author="557058:b8e64633-1f7c-402d-9caf-9959a5ba5d0d" created="Mon, 4 Mar 2019 14:40:51 +0000"  >&lt;p&gt;&lt;a href=&quot;https://folio-org.atlassian.net/secure/ViewProfile.jspa?accountId=5ae08bd47b44642d39d323c4&quot; class=&quot;user-hover&quot; rel=&quot;5ae08bd47b44642d39d323c4&quot; data-account-id=&quot;5ae08bd47b44642d39d323c4&quot; accountid=&quot;5ae08bd47b44642d39d323c4&quot; rel=&quot;noreferrer&quot;&gt;Mike Gorrell&lt;/a&gt; please review this issue so David can resolve it.&lt;/p&gt;</comment>
                                                            <comment id="192232" author="61cd0ca0bce5e00069e98be7" created="Tue, 5 Mar 2019 13:43:31 +0000"  >&lt;p&gt;Refer to the &quot;&lt;a href=&quot;https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#markdown&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;RAML 1.0 specification&lt;/a&gt;&quot; regarding Markdown, and use find-in-page &quot;markdown&quot; to show where it can be utilised.&lt;/p&gt;</comment>
                                                            <comment id="192233" author="61cd0ca0bce5e00069e98be7" created="Wed, 6 Mar 2019 02:29:47 +0000"  >&lt;p&gt;Closed. The demo is sufficient to provide some examples.&lt;/p&gt;</comment>
                                                            <comment id="192234" author="5bffed52a1b46046f530c8f7" created="Fri, 15 Nov 2019 13:28:42 +0000"  >&lt;p&gt;For the record: I have used these facilities to add a discursive introduction to the Course Reserves API. You can see the simple change I made at &lt;a href=&quot;https://github.com/folio-org/mod-courses/commit/0001247c1e4d663745ae0477174bc8f89db189b4&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;https://github.com/folio-org/mod-courses/commit/0001247c1e4d663745ae0477174bc8f89db189b4&lt;/a&gt; and view the results in the &lt;b&gt;mod-courses&lt;/b&gt; section at &lt;a href=&quot;https://dev.folio.org/reference/api/#mod-courses&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;https://dev.folio.org/reference/api/#mod-courses&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;I have often felt that auto-generated docs are of very low utility because they give no context about &lt;em&gt;why&lt;/em&gt; one would use a given type or API. This kind of brief scene-setting prose can make a world of difference. I hope we get into a habit of doing this.&lt;/p&gt;</comment>
                    </comments>
                    <attachments>
                            <attachment id="64154" name="folio-1833-sources.zip" size="2356" author="61cd0ca0bce5e00069e98be7" created="Wed, 6 Mar 2019 02:29:11 +0000"/>
                            <attachment id="64155" name="view-1.html" size="44760" author="61cd0ca0bce5e00069e98be7" created="Fri, 1 Mar 2019 02:15:04 +0000"/>
                            <attachment id="64156" name="view-2.html" size="39780" author="61cd0ca0bce5e00069e98be7" created="Fri, 1 Mar 2019 02:15:04 +0000"/>
                    </attachments>
                <subtasks>
                    </subtasks>
                <customfields>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                <customfield id="customfield_10000" key="com.atlassian.jira.plugins.jira-development-integration-plugin:devsummarycf">
                        <customfieldname>Development</customfieldname>
                        <customfieldvalues>
                            
                        </customfieldvalues>
                    </customfield>
                                                                <customfield id="customfield_10057" key="com.atlassian.jira.plugin.system.customfieldtypes:select">
                        <customfieldname>Development Team</customfieldname>
                        <customfieldvalues>
                                <customfieldvalue key="10144"><![CDATA[Core: Platform]]></customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        <customfield id="customfield_10019" key="com.pyxis.greenhopper.jira:gh-lexo-rank">
                        <customfieldname>Rank</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>0|hzx867:</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    <customfield id="customfield_10020" key="com.pyxis.greenhopper.jira:gh-sprint">
                        <customfieldname>Sprint</customfieldname>
                        <customfieldvalues>
                                <customfieldvalue id="1148">Core: Platform - Sprint 58</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                                            <customfield id="customfield_10044" key="com.atlassian.jira.plugin.system.customfieldtypes:float">
                        <customfieldname>Story Points</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>1.0</customfieldvalue>
                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                <customfield id="customfield_10024" key="com.atlassian.jira.ext.charting:firstresponsedate">
                        <customfieldname>[CHART] Date of First Response</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>Mon, 4 Mar 2019 14:40:51 +0000</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                <customfield id="customfield_10025" key="com.atlassian.jira.ext.charting:timeinstatus">
                        <customfieldname>[CHART] Time in Status</customfieldname>
                        <customfieldvalues>
                            
                        </customfieldvalues>
                    </customfield>
                                    </customfields>
    </item>
</channel>
</rss>