Chapel: Bring developer documentation online

[ben-albrecht]

Currently, the developer best practices documentation lives in doc/rst/developer/bestPractices mostly in the form of raw text files. Eventually, we would like to:

• Convert these text files to formatted Sphinx-flavored ReStructured Text

  • This is the [good first issue] component of this issue, due to the small barrier of entry to contributing to the project:
  • [x] adding-a-comm-layer.txt
  • [x] adding-a-runtime-component.txt
  • [x] adding-a-tasking-model.txt
  • [x] internal-errors.txt
  • [x] bestPractices/
    
    
    
    • [x] CompilerDebugging.rst
    
    
    • [x] CompilerIRTricks.rst
    
    
    • [x] CHPL_DEVELOPER.rst
    
    
    • [x] Deprecation.rst
    
    
    • [x] GASNetOnDesktops.rst
    
    
    • [x] GettingStarted.rst
    
    
    • [x] Potpourri.rst
    
    
    • [x] RuntimeLibrary.rst
    
    
    • [x] TestAnnotationsLocally.rst
    
    
    • [x] Valgrind.rst
    
    
    • [x] ContributorInfo.rst
    
    
    • [x] ErrorWarningMessaging.rst
    
    
    • [x] GeneratedCode.rst
    
    
    • [x] NightlyTesting.rst
    
    
    • [x] README.rst
    
    
    • [x] SpellChecking.rst
    
    
    • [x] TestSystem.rst
    
    
    • [x] buildingdocs.rst
    
    

• Review and update the content from doc/developer/bestPractices

  • Furthermore, much of the content from chapel-lang.org/gsoc could be converted into developer documentation
• Decide how to build and host developer documentation:
  
  
  
  • option 1: Always build with developer docs, and host under:
    
    
    
    
    
    • https://chapel-lang/docs/master/
    
    
    
  
  
  • option 2: Only build developer docs when CHPL_DEVELOPER=true, host under something like:
    
    
    
    
    
    • https://chapel-lang/docs/developer/ (not a real link)
    
    
    
  
  

[ben-albrecht]

As part of this effort, http://chapel.cray.com/gsoc/contributing.html should be combined into ContributorInfo.rst

[KING-SID]

Hey @ben-albrecht ! Is this issue still open? If so, I'd like to take on this issue, can you please advise me on how I can go about this? The link to the bestPractices file seems to no longer be active.

[ben-albrecht]

Hey @KING-SID, thanks for letting me know about the dead link - I've updated the text above.

As the issue mentions, the "good first issue" part of this task is to convert the text files in the developer documentation into restructured text format so that we may build them into a sphinx project similar to the Chapel documentation.

Some documentation on restructured text can be found here: http://docutils.sourceforge.net/rst.html

If I were tackling this task, I'd build a bare bones sphinx project within doc/rst/developer/ and start adding files as I converted them to rst, using sphinx to compile the rst into HTML to see how they render.

[KING-SID]

@ben-albrecht Thanks, I'll get right to it!

[KING-SID]

Hey @ben-albrecht I just wanted to get a clarification on the issue. Is the preliminary part of the issue to convert all the .txt files in this section to rst or only those in the bestPractices folder within that section?

[ben-albrecht]

I just wanted to get a clarification on the issue. Is the preliminary part of the issue to convert all the .txt files in this section to rst or only those in the bestPractices folder within that section?

Hey @KING-SID - I'd suggest sticking with bestPractices/ for now. We can add other files later.

[ben-albrecht]

It might also be a good idea to open a pull request for just a single file you've converted, so that you can get some early feedback/corrections before getting too far along. Thanks!

[KING-SID]

@ben-albrecht Will do. It seems that most of the files have already been witten in rST are there any changes to be made to these documents in terms of formatting or is simply converting from .txt to .rst it required?

[ben-albrecht]

I've updated the issue description to include a checklist of remaining documents to be rst-ified. Many of them are almost rst-friendly, several are currently markdown, and a few are completely unformatted.

[krishnadey30]

Hey @ben-albrecht is someone working in it?

[KING-SID]

Hey @krishnadey30 I am currently working on this, but we can work on this together so that it can be done faster. There are 10 files left to convert - how about we split it 5 each?
I'll be taking CompilerIRTricks.rst, GettingStarted.rst, CHPL_DEVELOPER.rst, GASNetOnDesktops.rst and Potpourri.rst. Feel free to work on the other 5. Cheers!

[krishnadey30]

@KING-SID Thanks. I will let you know when I am done.

[krishnadey30]

@KING-SID I have created a PR for this. What's your status.

[krishnadey30]

As part of this effort, http://chapel.cray.com/gsoc/contributing.html should be combined into ContributorInfo.rst

This link is not available anymore.I think this is the updated link https://chapel-lang.org/contributing.html

[krishnadey30]

As part of this effort, http://chapel.cray.com/gsoc/contributing.html should be combined into ContributorInfo.rst

I would like to take this up.

[krishnadey30]

@ben-albrecht I have modified

• CHPL_DEVELOPER.rst
• CompilerIRTricks.rst
• GASNetOnDesktops.rst
• GettingStarted.rst
• Potpourri.rst

and have opened a PR https://github.com/chapel-lang/chapel/pull/12690 for the same. Kindly take a look.

[ben-albrecht]

I've added a few other text files that remain un-rstified. Once we get those converted, I think we can remove [good first issue] from this issue (or close this one and open a new one primarily about the mechanism of hosting developer docs).

[krishnadey30]

@ben-albrecht I would like to complete this.

[krishnadey30]

@ben-albrecht I have modified

• adding-a-comm-layer.txt
• adding-a-runtime-component.txt
• adding-a-tasking-model.txt
• internal-errors.txt

and have opened a PR #12710 for the same. Kindly take a look.

[krishnadey30]

@ben-albrecht Can you tell me which parts of chapel-lang.org/gsoc should be converted into developer documentation. I feel we should do this asap.