Quick Documentation

[strikeraryu]

Summary of Problem

The documentation provided by the chapel right now has a very detailed explanation about the library utilities provided by the chapel. So if someone is switching from another language who is familiar with the concepts has to spend more time when he wants to brief about the utilities as there is no quick reference material for utilities.

Solution

We can add quick reference material for each growing library which added in chapel and make it a basic requirement for adding a library. It will provide quick details about the utilities provided by each library, So it will be much easier to utilize chapel to the fullest. Each quick documentation will be index in categories so it is easy to navigate.

Basic template (subject of discussion)

Few basic details

List of all members < member_name - use - link >

List of all functions < function_name - use - args - link >

---

Something like in c++ reference material.

[bradcray]

@strikeraryu : How would such documentation compare to https://github.com/chapel-lang/chapel/blob/master/doc/rst/language/quickReference.pdf

[strikeraryu]

@bradcray the details provided are some goto syntax for chapel, the one I am talking about is for growing libraries so we can check all the functionality provided in a glance and providing quick usage. should I elaborate more?

[bradcray]

Got it, thanks. The focus on library capabilities in this issue wasn't clear to me from the issue's title or OP. It might be worth editing to clarify this. I'm also curious whether you're proposing having a short overview of capabilities defined by a library within each library's own documentation; or a single summary that rolls up all (standard) library capabilities within a single place?

[strikeraryu]

Yeah, I am proposing to add for each library rather than all in one place, and each quick documentation will be index in categories so it is easy to navigate. I will edit the issue with better details. I think c++ reference material is a good example have a look.

[bradcray]

That sounds attractive to me. Some libraries already do something like this informally, though not with the one-line descriptions as you suggest. For example, I'm thinking of: https://chapel-lang.org/docs/modules/standard/FileSystem.html#file-directory-manipulations

[strikeraryu]

If we are going through this addition in documentation we have to think about the format of the template, the 2 key points that I can think of is one the details should be enough that a user can relate to its previous knowledge, and second, the information should be in a small format both visually and content-wise so the user is not wasting his time to get the important details. PS: should I propose something, like a test template then we can further improve on that.

[strikeraryu]

So are we going through this, I understand it will not be a straightforward task but will require much more planning than this. But adding quick reference might help the chapel community in the long run.

[bradcray]

@strikeraryu : In general, for design discussions / decisions like this, it's good to engage the community to get reactions to the proposal and see whether there's general enthusiasm, or distaste, for the proposal. When you're ready to have that discussion, I'd recommend engaging the community by posting to Discourse, referring them to this issue.

For me specifically, I think the end-result could be attractive, but before giving a final thumbs-up, would want/need to understand how a module would opt into it, and how we would maintain it over time. E.g., would it be manually maintained as a separate piece of data at the top of each library's file-level documentation comments (in which case, it would be nice to have scripts that ensured that there was a 1:1 correspondence between entries in the summary table and the main module docs)? Or would we have the chpldoc comment for each publicly documented declaration contain some sort of "headline" entry which would be used to create this table?

[strikeraryu]

Yeah, I will formulate a Discourse post, so everyone can review it and provide their suggestion if this will be viable and manageable or not.

[mppf]

The general idea sounds nice to me, assuming that we're talking about creating optional functionality for chpldoc. I also wonder about some of the questions along the lines of what Brad asked above - e.g. how does a module author opt in to it? how does chpldoc identify the "headline" vs the more detailed documentation?

[strikeraryu]

I think we can add an option like if the author wants to add a different headline than the detailed one then we can use some prefix or symbol to describe that and if this is not provided we can take the main string as it is. Now, this will be easy when working for new libraries but for the ones already implemented we have to find some way, top of my head is if we can create a list of all function where their description is exceeding the specific character limit using some script and based on the amount of those we can think some way, like if it is less we can manually add one line descriptors but if it is a lot we can do to something else.

[lydia-duncan]

There's probably a way to generate an index of some sort. I've definitely appreciated things like this in the past. Are we aware of other projects that use Sphinx doing this? There may be a pattern that handles it already with minimal implementation effort (along the lines of how readthedocs as a template handles a lot of the visual layout aspects)

[strikeraryu]

Are we aware of other projects that use Sphinx doing this? There may be a pattern that handles it already with minimal implementation effort

Yeah I was looking into it and I realized there is Sphinx has an option of creating auto summary which will give results very close to our requirements. I was trying to look for documentation who are using that but it is a little tough to find as the google search engine shows the result about Sphinx documentation rather than the websites that are using Sphinx autocomplete if I try to look up. This is what stated in their documentation about Sphinx autocomplete.

Insert a table that contains links to documented items, and a short summary blurb (the first sentence of the docstring) for each of them.

These is the results we can get using Sphinx auto summary.

[lydia-duncan]

Neat! Seems like something it would be nice to turn on with a flag to chpldoc itself that turns on the Sphinx auto summary, if possible. We'd want to look at our generated module documentation with this to ensure that it's not repeating itself unnecessarily and that the first line it grabs is appropriate before turning it on for the documentation that we host. This will be probably a bit of effort considering how much documentation we have, though.

So I'd start with looking into how to enable it with a flag and save a test that locks in that it works. Then we can talk about the module documentation

[strikeraryu]

We'd want to look at our generated module documentation with this to ensure that it's not repeating itself unnecessarily and that the first line it grabs is appropriate before turning it on for the documentation that we host

Yeah and maybe we have to also check is it compact enough for our usage or it will be just another form of our original documentation. Let see what will be the results and can we improve upon them.