[Archivesspace_api_doc_adhoc] Question about routes and examples

[David W. Hodges]

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.)

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 "Get a list of system users
<https://archivesspace.github.io/archivesspace/api/?shell#get-a-list-of-system-users>"
shows a simple Curl example. But looking at users.rb
<https://github.com/archivesspace/archivesspace/blob/master/backend/app/controllers/users.rb#L70>,
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.

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?

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.

Any hints would be appreciated. If this is all covered in the video
tutorials I'll go back and listen more carefully ;)

Thanks, I'm looking forward to getting started for real and making progress!

David

-- 
David W. Hodges
Special Collections Analyst
Columbia University Libraries
Butler Library
535 West 114th St.
New York, NY 10027
212 854-8758
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lyralists.lyrasis.org/pipermail/archivesspace_api_doc_adhoc/attachments/20200920/ccef8849/attachment.html>