[List] Suggestions regarding the Documentation

[denis-migdal]

Here a list of suggestions regarding the Brython documentation :
@PierreQuentel For each items, if you answer 'no', I'll remove them from the list.

• [Home] Why Brython (more info) ?
• [Doc Menu] Change the structure of the documentation (I can get students on it for a project) (more info)
  • Add a link to the Github Wiki ?
  • + background-color of categories : more dark for better readability.
  • Use accordions in the menu (e.g. with details/summary HTML Elements)
  • Add a float:right or a sticky page menu at the top of pages for better browsing (more info)
• [Modules] Gather together pages regarding Brython modules (more info)
  • [import] Erroneous information : resolution of import seems outdated/wrong (more info)
• [webcomponent] State that attachShadow() can't be used in some HTMLElement (more info).
• [webcomponent] State that children should either be added in the constructor in a shadow DOM, or be added in connectedCallback() (call be called several times !). Else, createElement() will refuse to build the element (more info)
• [Syntax] State that usage of console.log() should be preferred to print() for better output formatting, e.g. when printing HTMLElement (more info).
• [All examples] Add async attribute in <script src='brython.js' async> in all Brython code (more info).
• [Cookbooks] Add Cookbooks with the JS/DOM API (I can write them).
• [Console/Editor] : select Brython version ?
• [Website Menu] :
  • [Language] : replace the discrete select by a big flag image in the Brython menu ?
  • [Tutoriel/Cookbooks/Demo/Galleries] : why 4 different pages ? Replace by a menu "Examples" => than can have a submenu with theses pages ?
  • [Website Menu] : use dropdown ?
  • [Website Menu] : "getting Started" page outside of the doc ?
  • [Website Menu] : add a Benchmark page ?
  • [Website Menu] : console/editor : put at as a submenu (dropdown ?), menu could be in "getting Started", submenu, and in the "getting Started" page, after the hello word : try it out with out console/editor + link the to documentation.
• [Console] Improve the copy/paste (many empty lines when copying)

[denis-migdal]

Here an example for the page menu :

details {
	position:fixed;
	right:5em;
	top: 5em;
	z-index: 100;
	background: var(--color-box-body);
	border: 1px solid gray;
	border-radius: 5px;
	padding: 10px;
	padding-right:20px;
	margin-bottom: 0px;
	& > ul { margin-bottom:0px
	} }

<details open=""><summary>Table of Contents</summary><ul>
<li>
<a href="#user-content-keyapp" rel="nofollow">KeyApp</a></li>
<ul>
<li>
<a href="#user-content-links" rel="nofollow">Links</a></li>
<li>
<a href="#user-content-commands" rel="nofollow">Commands</a></li>
<li>
<a href="#user-content-install" rel="nofollow">Install</a></li>
<li>
<a href="#user-content-custom-css" rel="nofollow">Custom CSS</a></li>
</ul>
</ul>
</details>

[denis-migdal]

I read some comments online about Brython, and it seems its advantages aren't clear enough :

E.g. "4 reasons to use Brython:"

1. Ofc, not requiring to learn JS if you know Python / same language client/server / easy learning curve.
2. Use Python-like API or access full JS/DOM API
   a. With easy interactions JS <=> Python.
   b. Support usage of both Python and JS existing library in Python
3. Performant : JIT and pre-compiled.
4. Better than alternatives ? (cf also)
   a. Well maintained compared to alternatives
   b. Full CPython support.
   c. Small size compared to alternatives that ships Python interpreter (200kB once compressed vs 10MB).
   d. Faster (link to benchmark see this)
   e. Big community (6k stars)

I think that once perfs are improved (cf related issue), and documentations restructured, we could contact some specialized Python/Info news websites (e.g. developpez.com in France) to promote Brython and inform people of the recent changes ? Could help Brython adoption (?).

[denis-migdal]

Added lot of suggestions for the Website Menu.

[denis-migdal]

Another issue related to documentation : #980.