<html xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Generator" content="Microsoft Word 15 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
font-size:11.0pt;
font-family:"Calibri",sans-serif;}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
span.EmailStyle18
{mso-style-type:personal-reply;
font-family:"Calibri",sans-serif;
color:windowtext;}
.MsoChpDefault
{mso-style-type:export-only;
font-size:10.0pt;}
@page WordSection1
{size:8.5in 11.0in;
margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
{page:WordSection1;}
--></style>
</head>
<body lang="EN-US" link="blue" vlink="purple" style="word-wrap:break-word">
<div class="WordSection1">
<p class="MsoNormal">I think it’s briefly covered in the video tutorials, but there’s no reason you should have to go pick through them.
<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">To summarize, the examples are actually built during the build process that generates the documentation. Specifically, they’re created using the FactoryBot test mock factories (defined here
<a href="https://github.com/archivesspace/archivesspace/blob/master/backend/spec/factories.rb">
https://github.com/archivesspace/archivesspace/blob/master/backend/spec/factories.rb</a>), during the portion of building the docs that lives in the test harness (here:
<a href="https://github.com/archivesspace/archivesspace/blob/master/backend/spec/documentation_spec.rb">
https://github.com/archivesspace/archivesspace/blob/master/backend/spec/documentation_spec.rb</a>).<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">This gets saved to two files, I believe in the root directory of the project:
<br>
<br>
<o:p></o:p></p>
<p class="MsoNormal">endpoint_examples.json.<o:p></o:p></p>
<p class="MsoNormal">endpoint_examples_problems.json<o:p></o:p></p>
<p class="MsoNormal"><o:p></o:p></p>
<p class="MsoNormal">The examples that show up defined in code are the ones that someone’s added to override the ones generated automatically by this method, i.e. the thing we’re doin’ in this project!
<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">The automated _<i>documentation</i>_, on the other hand, Is generated based on properties of the endpoint (i.e. whether it’s paginated or deprecated) and is in the ERB template that generates the Slate documentation. I can describe it in
more depth if need be, but fundamentally I think the mechanism doesn’t matter to the project – I’d recommend just looking at the published docs to see if the examples or documentation are sufficient, and then going to the code or putting docs/examples in the
spreadsheet as needed. <o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<div>
<p class="MsoNormal">--<o:p></o:p></p>
<p class="MsoNormal">Dave Mayo (he/him)<o:p></o:p></p>
</div>
<p class="MsoNormal">Senior Digital Library Software Engineer<br>
Harvard University > HUIT > LTS<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<div style="border:none;border-top:solid #B5C4DF 1.0pt;padding:3.0pt 0in 0in 0in">
<p class="MsoNormal"><b><span style="font-size:12.0pt;color:black">From: </span></b><span style="font-size:12.0pt;color:black"><archivesspace_api_doc_adhoc-bounces@lyralists.lyrasis.org> on behalf of "David W. Hodges" <dwh2128@columbia.edu><br>
<b>Reply-To: </b>"archivesspace_api_doc_adhoc@lyralists.lyrasis.org" <archivesspace_api_doc_adhoc@lyralists.lyrasis.org><br>
<b>Date: </b>Sunday, September 20, 2020 at 11:10 AM<br>
<b>To: </b>"archivesspace_api_doc_adhoc@lyralists.lyrasis.org" <archivesspace_api_doc_adhoc@lyralists.lyrasis.org><br>
<b>Subject: </b>[Archivesspace_api_doc_adhoc] Question about routes and examples<o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">Hi all. OK, after some struggle I managed to build the docs anew on my Mac. So far so good! (BTW, if anyone is good at this on Linux I'd appreciate any help, as I tried on Ubuntu but ran into a cascade of errors and gave up; I'd like to
get this working on that machine eventually though.)<o:p></o:p></p>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">Looking at a few routes, I am unsure where exactly the code examples are (or should be) stored. In some cases the code is in the .rb file, but in others it isn't. For example, the entry for "<a href="https://urldefense.proofpoint.com/v2/url?u=https-3A__archivesspace.github.io_archivesspace_api_-3Fshell-23get-2Da-2Dlist-2Dof-2Dsystem-2Dusers&d=DwMFaQ&c=WO-RGvefibhHBZq3fL85hQ&r=_Mv1dY22K7jvT5MD7xjbvGVzRDOUMhx4WYcnPSIzYnE&m=lXXvcKi5ALsf7jeGlOk3EwMIOxz7Yo8ymlyFcn9GTxM&s=j7X0iyj357P3BU0v0VQcCgH98PnLZMimRGInlfCTDkU&e=">Get
a list of system users</a>" shows a simple Curl example. But looking at <a href="https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_archivesspace_archivesspace_blob_master_backend_app_controllers_users.rb-23L70&d=DwMFaQ&c=WO-RGvefibhHBZq3fL85hQ&r=_Mv1dY22K7jvT5MD7xjbvGVzRDOUMhx4WYcnPSIzYnE&m=lXXvcKi5ALsf7jeGlOk3EwMIOxz7Yo8ymlyFcn9GTxM&s=mZJ5zna87MBEhFDoyM8CbE3CsjXUSI5ndjmk90yVI_E&e=">
users.rb</a>, there is no .example code that I can find. Whereas in other routes like Dave showed, the examples are right there in the controller adjacent to the other route documentation.<o:p></o:p></p>
</div>
<div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">I recall something about the "prepend" attribute and determining whether things overwrite existing documentation or not (presumably in the markdown file index.md, I guess?). Is that what's going on here? I had thought the markdown was generated
downstream from the controllers, but is it more of a merge from two different sources? <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">And for the sake of maintainability, should we strive to make the documentation more uniform and single-source? I'm not really familiar with best practices here, just wondering more from a documentation management perspective.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">Any hints would be appreciated. If this is all covered in the video tutorials I'll go back and listen more carefully ;) <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">Thanks, I'm looking forward to getting started for real and making progress!<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">David<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<p class="MsoNormal">-- <o:p></o:p></p>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<p class="MsoNormal"><span style="font-size:10.0pt;color:#999999">David W. Hodges</span><span style="font-size:10.0pt"><o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:10.0pt;color:#999999">Special Collections Analyst</span><span style="font-size:10.0pt"><o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:10.0pt;color:#999999">Columbia University Libraries</span><span style="font-size:10.0pt"><o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:10.0pt;color:#999999">Butler Library</span><span style="font-size:10.0pt"><o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:10.0pt;color:#999999">535 West 114th St.</span><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:10.0pt;color:#999999">New York, NY 10027</span><span style="font-size:10.0pt"><o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:10.0pt;color:#999999">212 854-8758</span><span style="font-size:10.0pt"><o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:10.0pt;color:black"><o:p> </o:p></span></p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</body>
</html>