Pull request format discussion

[IcePigZDB]

PR format discussion

discussion are welcome.

Preview

Summary of talk

Date:

Topic:

Keywords:

Format check List

• Conforming to English specifications especially in README.md.
• Capitalize the first letter.
• Use English punctuation with appropriate space.
• ...
• Remember to add links to reference papers.
• Make sure the link is accessible.
• Use - to connect filename rather than , the latter will casue dead link.
• Make sure latex formulas display normally, more can be found in #31.
• Pass the markdown lint check, more can be found in #31.

Key points

Dispaly latex formulas in github flavored markdown

1. Github has supported mathematical expressions in markdown , more information please refer to this blog. 🎉🎉🎉

2. readme2tex.

3. rendor latex formula to image with Github official service.
   https://render.githubusercontent.com/render/math?math=

   • Vscode extension math to image.

   • Use a scripts, a simple example in python, style ref is math to image, code ref repo.
     Save as python script and run python3 script-filename.py target-markdown-filename.md.

   import sys
   import re
   from urllib.parse import quote
   # $$
   # formula
   # $$
   interline_tag = '\n<img src="https://render.githubusercontent.com/render/math?math={}" class="ee_img tr_noresize" eeimg="1">\n'
   interline_pattern = '\$\$\n*((.|\n)*?)\n*\$\$' # (.|\n) . or \n
   # $formula$
   inline_tag = '<img src="https://render.githubusercontent.com/render/math?math={}" class="ee_img tr_noresize" eeimg="1">'
   inline_pattern = '\$\n*(.*?)\n*\$'
   
   def replace_tex(content):
   	def dashrepl_quote(matchobj, tag):
   		formular = matchobj.group(1)
                   # quote & to %26 etc in $$ x&= a+1$$, otherwise, thers will be error when render with githubusercontent.com
   		formular = quote(formular) 
   		return tag.format(formular, formular)
   
   	content = re.sub(interline_pattern, lambda mo: dashrepl_quote(mo, interline_tag), content)
   	content = re.sub(inline_pattern, lambda mo: dashrepl_quote(mo, inline_tag), content)
   
   	return content
   
   if __name__=='__main__':
   	assert len(sys.argv) > 1, "Error: need filename as a argument"
   	filename = sys.argv[1]
   	with open(filename, mode='r',encoding='utf-8') as f:
   		content = f.read()
   	with open(filename, mode='w',encoding='utf-8') as f:
   		f.write(replace_tex(content))

   Rendering multi-line formula example with githubusercontent:

   $$
   \begin{align}
   x = v_0\cos\theta t\\
   y = v_0\sin\theta t - \frac{1}{2}gt^2
   \end{align}
   $$

   

   $$
   \begin{align}
   x &= v_0\cos\theta t\\
   y &= v_0\sin\theta t - \frac{1}{2}gt^2
   \end{align}
   $$

   

   $$
   x = v_0\cos\theta t\\
   y = v_0\sin\theta t - \frac{1}{2}gt^2
   $$

   

   Please use \begin{align} to display in rows.
   More discussion in stackoveflow.

[ehds]

Github has supported mathematical expressions in markdown , more information please refer to this blog. 🎉🎉🎉
Inline example: mass-energy equation $E=mc^2$

multi-line example： Maxwell's equations

$$ \begin{cases} \nabla \cdot \mathbf{E} = \frac{\rho}{\epsilon_0} \\ \nabla \times \mathbf{E} = -\frac{\partial}{\partial t} \mathbf{B} \\ \nabla \cdot \mathbf{B} = 0 \\ \nabla \times \mathbf{B} = \mu_0 \mathbf{J} + \mu_0 \epsilon_0 \frac{\partial}{\partial t} \mathbf{E} \\ \end{cases} $$

[IcePigZDB]

Markdown lint

Markdown lint check for new PR has ben introduced by #41, #43 .

To make it easier for you to pass the check, here is a possible way.

• Write your mardown file on vscode with two plugins:

  • Markdown All In Ene
  • markdownlint

• Format markdonw file by vscode format api according to vscode doc.

More approaches are welcome 😊.