Bring developer documentation online

ben-albrecht commented 7 years ago

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 commented 7 years ago

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

KING-SID commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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

KING-SID commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

@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 commented 5 years ago

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.