search

atom / atom.io

🌐 A place for feedback on the atom.io website and package API
158 stars 98 forks source link

Documentation on code spans in config schema #167

Closed zypA13510 closed 5 years ago

zypA13510 commented 5 years ago

Although I can infer from the markdown syntax that code spans are quoted by backticks `, but the documentation here really confused me.

Why do we have this

code spans - \code spans``

instead of this? code spans - `code spans`

Btw, I can't seem to find the source code of documentation anywhere.

Aerijo commented 5 years ago

@zypA13510 I believe that's 'just' the markdown generator making a mistake. The source for that is here, and they are clearly trying to put in escaped back ticks like you suggest. It's still an issue, just a different reason.

zypA13510 commented 5 years ago

@Aerijo No, I think maybe they made a mistake here?

`code spans` - `\`code spans\``

code spans - \code spans``

`code spans` - `` `code spans` ``

code spans - `code spans`

You mentioned that the documentation is generated from the source? So if I make a PR fixing that and the doc will be fixed too?

Aerijo commented 5 years ago

I meant that the backslashes seem to be to escape the `, but you're right that that's not how GFM markdown works.

I believe a PR would fix it, but I don't know how to run the generator to check. It could be they are using one that doesn't support arbitrary backticks starting code snippets.

Arcanemagus commented 5 years ago

The source is parsed with joanna and that metadata is turned into an intermediate format with tello that then gets turned into the final documentation with atomdoc.

It's... complicated to debug, however I made it quite a bit simpler when I added the --generate-api-docs command to the build script.