Problem/Motivation

Currently, README.md files are not available for each sub-modules. Instead, the documentation is contained within the .module files to facilitate parsing by api.drupal.org.

As a coder who reads source code, I prefer to read the README first. Visiting api.drupal.org is an option, but usually, I was leading to there by search engines. If I have the source code on my local, I read the README.md first.

Meanwhile, we are using GitLab more and more, it parses README.md automatically.

And I read a message on slack recently that api.drupal.org was not working well.

Meanwhile, I am considering using ChatGPT to help and translate the README.md file into other languages. It can lower the barrier more or less for learning from the examples module.

All README.md files will be parsed/rendered automatically on GitLab as well. And each transition should be reviewed by a native before gets committed.

Steps to reproduce

Proposed resolution

  1. Continue with extracting a README.md from the .module file to avoid credits gaming, do it in one go, or do it with 3-5 submodules per batch.
  2. Extract a README.md file from the .module file for each submodule -- Chatgpt may help
  3. Remove those long comment blocks from .module files
  • To have an example of help_topics: help_topics_example, #3155111: Add help_topics example, postpone the implementation or integration of help_topics into examples.
  • Allow to accept translations of README.md, but optional, for the syncing. If the translation is outdated, give it a time window, e.g. one or two weeks to update, or it gets removed.

Take js_exmaple sub-module as the example, optional translation support with the following file structure:

README.md // English by default
README.translation
   - zh-hans/README.md // Chinese,
   - es/README.md // Spanish
   - fr/README.md // French
   ...

Or with the following file paths

  • js_example/README.md
  • js_example/README.translations/zh-hans/README.md
  • js_example/README.translations/es/README.md
  • js_example/README.translations/fr/README.md
  • ...

Fewer lines would be better in code or TLDR.

Remaining tasks

User interface changes

API changes

Data model changes

Comments

jungle created an issue. See original summary.

jungle’s picture

jungle
He/Him
Location Chongqing, China
commented
Title: [Police] Add README.md to each submodule or not » [Policy] Add README.md to each submodule or not
ressa’s picture

ressa
he/him
commented

I agree with your proposed resolution @jungle, moving the documentation out from each sub-module and into a README.md makes a lot of sense.

So, as an example, would it mean deleting this part from the js_example.module:

/**
 * @defgroup js_example Example: JavaScript
 * @ingroup examples
 * @{
 * Examples using Drupal 8's built-in JavaScript.
 *
 * We have two examples here.
 *
 * One 'weights' content and then sorts it by weight. This demonstrates
 * attaching JavaScript through Drupal's render arrays.
 *
 * The other demonstrates adding an accordion effect to content, through
 * Drupal's theme layer.
 */

... remove D8 reference, and add it to a new README.md file, like this?

# Examples using Drupal's built-in JavaScript.

We have two examples here.

One 'weights' content and then sorts it by weight. This demonstrates
attaching JavaScript through Drupal's render arrays.

The other demonstrates adding an accordion effect to content, through
Drupal's theme layer.
ressa’s picture

ressa
he/him
commented
Issue summary: View changes

Added child issue creation as a task under "Proposed resolution".

jungle’s picture

jungle
He/Him
Location Chongqing, China
commented

I copied and pasted the content of file_example.module file into chatgpt, and asked it to do it for me, it works well to me.

See the commit here

The sample instruction i used, FYI

Extract a REAME.md file from the content following, wrap it in less than 80 chars for each line of the answer and give me the answer in a markdown code block.

THE CONTENT OF THE MODULE FILE

jungle’s picture

jungle
He/Him
Location Chongqing, China
commented

So, as an example, would it mean deleting this part from the js_example.module:

Go ahead please with the suggestion in #5 if you like, thanks!

jungle’s picture

jungle
He/Him
Location Chongqing, China
commented
Title: [Policy] Add README.md to each submodule or not » [Policy] Add README.md to each submodule

Meanwhile, we are using GitLab more and more, it parses README.md automatically. Let's do it.

jungle’s picture

jungle
He/Him
Location Chongqing, China
commented
Issue summary: View changes
jungle’s picture

jungle
He/Him
Location Chongqing, China
commented

Re #3 yes, for the example of removal, see this commit

jungle’s picture

jungle
He/Him
Location Chongqing, China
commented

Meanwhile, I am considering using ChatGPT to help and translate the README.md file into other languages. It can lower the barrier more or less for learning from the examples module.

The file structure would be

README.md // English by default
README
   - zh-hans/README.md // Chinese,
   - es/README.md // Spanish
   - fr/README.md // French
   ...

All README.md files will be parsed/rendered automatically on GitLab as well. And each transition should be reviewed by a native before gets committed.

jungle’s picture

jungle
He/Him
Location Chongqing, China
commented
Title: [Policy] Add README.md to each submodule » [Policy] Add README.md to each submodule with optional getting translated
jungle’s picture

jungle
He/Him
Location Chongqing, China
commented
Issue summary: View changes
jungle’s picture

jungle
He/Him
Location Chongqing, China
commented
Issue summary: View changes
jungle’s picture

jungle
He/Him
Location Chongqing, China
commented

Or replace the folder name README with README_translations in the suggested file structure.

ressa’s picture

ressa
he/him
commented

Great idea with the different languages @jungle!

I found this page: https://gitlab.com/postgres-ai/database-lab/-/blob/master/translations/R... with path projectname/translations/README.german.md.

So maybe a structure like this would work, same as theirs?

README.md // English by default
translations
  - README.chinese-zh-hans.md
  - README.spanish.md
  - README.french.md
   ...

Maybe we should start out with creating the sub-theme README.md's from the .module content, since that text has been curated and written by one or more persons, but use ChatGPT for translating, like you suggest? At some point, the texts can be rewritten with the help of ChatGPT, if we decide so.

Also, are you able to create a "Documentation" option under "Component" for issues?

ressa’s picture

ressa
he/him
commented

I have created #3344564: Create README.md for Example: JavaScript sub-module (js_example) ready for review.

I used "JavaScript examples" for the header, since in that case, "examples" is used not as a name but a verb, from what I understand, reading https://www.drupal.org/drupalorg/style-guide/content.

Should we add README.md translations for sub-themes such as "JavaScript examples" as child issues under them, to keep it orderly?

jungle’s picture

jungle
He/Him
Location Chongqing, China
commented

Also, are you able to create a "Documentation" option under "Component" for issues?

Added

README.md // English by default
translations
- README.chinese-zh-hans.md
- README.spanish.md
- README.french.md
...

The structure works, but I still think the following is better.

README.md // English by default
README-translations // A directory indicates that there are README translations inside and ONLY!
    zh-hans // Using language code is fine, I think.
        README.md // Chinese translation, Entering this zh-hans, this is the only file, and Gitlab recognizes it automatically
    es // Spanish
        README.md // Spanish translation
    ...
jungle’s picture

jungle
He/Him
Location Chongqing, China
commented
Component: Other » Documentation
jungle’s picture

jungle
He/Him
Location Chongqing, China
commented

@ressa, I did send this issue to #examples-module and #documentaion in Drupal slack, hopefully, We can get agreement or feedback from them, and I would suggest holding on for a day or two, at least, before taking any further contributions. As I am not the only maintainer of this project, others may have different opinions. This is a kind of broken change. -- content of this module on api.drupal.org gets affected.

Many thanks!

ressa’s picture

ressa
he/him
commented

Thanks for the new "Documentation" Component :)

I prefer to keep paths and names short, and have all files in the same folder for less clicking, which is why I suggest this structure:

examples/translations/README.german.md

This is also fine:

examples/README-translations/README.german.md

What would be the benefits of having the translations in individual folders?

ressa’s picture

ressa
he/him
commented

Good idea, let's get some more opinions :)

jungle’s picture

jungle
He/Him
Location Chongqing, China
commented 
- README.md
- README-translations/zh-hans/README.md
- README-translations/es/README.md
- README-translations/fr/README.md
- ...

Suggested file pathes are the above. Or another variation: replace README-translations with README.translations

- README.md
- README.translations/zh-hans/README.md
- README.translations/es/README.md
- README.translations/fr/README.md
- ...
jungle’s picture

jungle
He/Him
Location Chongqing, China
commented

The root is each submodule, in my suggestion. E.g.

- js_example/README.md
- js_example/README.translations/zh-hans/README.md
- js_example/README.translations/es/README.md
- js_example/README.translations/fr/README.md
- ...

> What would be the benefits of having the translations in individual folders?

The benefit would be to visit URL_PREFIX_OMITTED/js_example/README.translations/zh-hans, you will see the Chinese README of js_example module, Just like clean URLs, eg, foo/bar/index,html, visit foo/bar, if it's foo/bar.index.html, you have to visit the exact path.

ressa’s picture

ressa
he/him
commented

Ah yes, the README.md would get rendered, true. In that case the number of clicks required to read the content would be the same with these two paths:

- js_example/README.translations/fr/README.md
- js_example/translations/README.french.md

jungle credited valthebald.

jungle’s picture

jungle
He/Him
Location Chongqing, China
commented

> valthebald: for README.md, will this be compatible with core's help_topics module?
> valthebald: it would be great to do so
> valthebald @jungle ^
> jungle: Hi, @valthebald no plan from me for that, to me, personally, it’s optional, README.md is enough for me as a dev. it’s an Experimental module in Drupal 9, I do not think it’s widely adopted by contrib modules, — just guess.
>jungle: even implementing hook_help is optional to me.

Chatting messages from slack.

ressa’s picture

ressa
he/him
commented

Great to see there's discussion going on, thanks for sharing!

jungle credited andypost.

jungle’s picture

jungle
He/Him
Location Chongqing, China
commented

There are more discussions continued with the above on slack, for the full messages in the thread, please view it here,

The summary we agreed on:

  • Continue with extracting a README.md from the .module file to avoid credits gaming, do it in one go, or do it with 3-5 submodules per batch.
  • To have an example of help_topics: help_topics_example, #3155111: Add help_topics example, postpone the implementation or integration of help_topics into examples.
  • Allow to accept translations of README.md, but optional, for the syncing. If the translation is outdated, give it a time window, e.g. one or two weeks to update or it gets removed.

Thanks @valthebald and @andypost

jungle’s picture

jungle
He/Him
Location Chongqing, China
commented
Issue summary: View changes

Updating Proposed resolution

jungle’s picture

jungle
He/Him
Location Chongqing, China
commented
Issue summary: View changes
jungle’s picture

jungle
He/Him
Location Chongqing, China
commented
Issue summary: View changes
avpaderno’s picture

avpaderno
he/him
Primary language Italian
Location Brescia, 🇮🇹 🇪🇺
commented
Status: Active » Closed (won't fix)

Since the plan described here is to remove the documentation comments and replace them with an external file, I would say this is a won't fix. Documentation in code is preferable because it requires editing a single file, instead of two or more files, which makes the process easier and less prone to mistakes.

I am not sure moving the information in Markdown files has any pro using api.drupal.org does not have. api.drupal.org is able to provide a list of classes, methods, functions, and constant that Markdown files are not able to provide.