Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Links in code reference (and example code) #1498

Open
gfwilliams opened this issue Sep 4, 2018 · 5 comments
Open

Links in code reference (and example code) #1498

gfwilliams opened this issue Sep 4, 2018 · 5 comments

Comments

@gfwilliams
Copy link
Member

gfwilliams commented Sep 4, 2018

Most of the Espruino reference page is really bad at linking through to other referenced functions. For example NRF.requestDevice may be mentioned in NRF.findDevices, but it should be a link so it can be clicked.

I recently changed the documentation builder so as long as the actual documentation contains the function/class/event's name inside single backticks, it should get automatically linked.

So, please can you flag up if:

  • If you see some bit of documentation that references some other part of the Espruino API that should be linked and isn't
  • Some bit of the documentation that should be in monospaced code font and isn't
  • If you notice something where an example would be handy, and you have a simple example

Maybe just post up here if you find something? Or you can fix it yourself:

  • Click on the icon to the right of the affected function's heading
  • It'll take you to where the documentation is in Espruino's code in GitHub
  • Make sure you're signed into GitHub and click the edit icon in the top right
  • Make the changes to the documentation (After the /*JSON{ .... } part you can just write code as simple Markdown). Put multiline code the three backticks ```, or just reference objects/functions/methods etc inline in a single backtick
  • Issue a pull request
@MaBecker
Copy link
Contributor

MaBecker commented Sep 4, 2018

something like this?

url: http://www.espruino.com/Reference#ArrayBuffer

link in text:

This is the built-in JavaScript class for array buffers.
If you want to access arrays of differing types of data you may also find /Reference#DataView useful.

points to: http://www.espruino.com/DataView
result:

404 - Page Not Found.
If you don't think you should have got this message, please Contact Us and let us know so that we 
can correct the problem!

:

gfwilliams added a commit that referenced this issue Sep 4, 2018
@gfwilliams
Copy link
Member Author

Thanks - I just added a fix for this and some other ArrayBuffer docs

@opichals
Copy link
Contributor

When executed in the JS console on the Reference page

This snippet:

ids = {};
for ([,n] of document.querySelectorAll('a[name]').entries()) {
    ids[n.getAttribute('name')] = n;
}

links = [];
for ([,n] of document.querySelectorAll('a[href]').entries()) {
    links.push(n.getAttribute('href'));
}

localLinks = links.filter(l => l.startsWith('#'));

localLinks.forEach(l => {
    if (!ids[l.slice(1)])
        console.log(`invalid href '${l}'`);
})

outputs the following:

invalid href '#t_l__global_Bluetooth'
invalid href '#t_l__global_I2C1'
invalid href '#t_l__global_I2C2'
invalid href '#t_l__global_I2C3'
invalid href '#t_l__global_LoopbackA'
invalid href '#t_l__global_LoopbackB'
invalid href '#t_l__global_Serial1'
invalid href '#t_l__global_Serial2'
invalid href '#t_l__global_Serial3'
invalid href '#t_l__global_Serial4'
invalid href '#t_l__global_Serial5'
invalid href '#t_l__global_Serial6'
invalid href '#t_l__global_SPI1'
invalid href '#t_l__global_SPI2'
invalid href '#t_l__global_SPI3'
invalid href '#t_l__global_Telnet'
invalid href '#t_l__global_Terminal'
invalid href '#t_l__global_USB'

@opichals
Copy link
Contributor

BTW the #1498 (comment) issue seem to still be there.

@gfwilliams
Copy link
Member Author

Thanks - the #1498 (comment) is still there because the docs are for 1v99, so the changes I put in aren't in those docs. If you do scripts/build_docs.py then it's fixed.

Good spot on the invalid hrefs though - just fixed that. Again though it won't take effect until the v2.00 release

@gfwilliams gfwilliams pinned this issue Feb 20, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants