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.

Sign up for GitHub

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

hide community doc links #1302

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

hide community doc links #1302

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 14 additions & 5 deletions src/blocks-ext.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,9 @@ BlockMorph.prototype.showHelp = async function() {
metadata = isServiceURL ?
await Services.getServiceMetadataFromURL(serviceName) :
await Services.getServiceMetadata(serviceName);

const isFSService = !!metadata.servicePath;
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm... It isn't obvious to me that this should be exposed in the metadata (which makes me a bit reluctant to have other features depend on it). Perhaps there is a better way to capture this information (ie, if it has official documentation) in the metadata and then use that here instead.

Copy link
Author

@dragazo dragazo May 12, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@brollb So PyBlox currently uses this when generating static wrappers, but that's only when building the wrappers for a new release, so we can change it without breaking anything. But just like here, that's only to filter to official services, so maybe just an isOfficial boolean would be better then - I'll just have to double check that we weren't using it for anything important in doc gen.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

agreed. I suspect there might be something better than isOfficial but I am not exactly sure what just yet.

My issue with isOfficial is that the server-side has been decoupling these further and further and there may be a more general term rather than isOfficial for 3rd party service hosts to designate that they have documentation. (Even in the current server, you can specify additional URLs to use for services and nest them under a dedicated category.)

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@brollb 3rd party as in similar to Community services? Or as in extra services only available on their deployment? (If it's like Community services, we probably don't want to be putting unmoderated external links even if they do have docs)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For example, you could make services.c2stem.org which could be nested under an arbitrary c2stem category. Here is an example services server written in Python: https://github.com/NetsBlox/Custom-Python-Services.

In the new cloud, they can be edited using the CLI here. Basically, they can be defined for individual users or class/groups. When they are registered, they require a URL and categories to be nested under. This allows them to show up in the NetsBlox browser for the affected users and they can implement basic request-reply (no message passing). If they need access to user information and message passing capabilities, they must be authorized by an admin of the NetsBlox cloud. This authorizes them to use some protected endpoints which should only be used by trusted servers as they can look up user states, send messages, etc.


if (methodName !== '') {
metadata = metadata.rpcs[methodName];
help = metadata.description;
Expand All @@ -53,13 +56,19 @@ BlockMorph.prototype.showHelp = async function() {
var optionalStr = arg.optional ? '[optional]' : '';
help += `\n${arg.name}: ${arg.description} ${optionalStr}`;
}
// add a direct link to the official docs page
const cat = metadata.categories && metadata.categories.length ? metadata.categories[0] : 'index';
help += `\n\nDocumentation can be found at:\n${SERVER_URL}/docs/services/${serviceName}/${cat}.html#${serviceName}.${methodName}`;

if (isFSService) {
// add a direct link to the official docs page
const cat = metadata.categories && metadata.categories.length ? metadata.categories[0] : 'index';
help += `\n\nDocumentation can be found at:\n${SERVER_URL}/docs/services/${serviceName}/${cat}.html#${serviceName}.${methodName}`;
}
} else { // get service description
help = metadata.description;
// add a direct link to the official docs page
help += `\n\nDocumentation can be found at:\n${SERVER_URL}/docs/services/${serviceName}/index.html`;

if (isFSService) {
// add a direct link to the official docs page
help += `\n\nDocumentation can be found at:\n${SERVER_URL}/docs/services/${serviceName}/index.html`;
}
}
if (!help) help = 'Description not available';
} else {
Expand Down