electron/algolia-indices

Algolia search index data for Electron APIs, Tutorials, Packages, and Repos

Electron Algolia Indices

Searchable data about Electron APIs, Tutorials, Packages, Repos, and Apps

Data Sources

Type	Source
APIs	electron-api.json
Tutorials	electron/i18n
Packages	electron/packages
Repos	electron/repos
Apps	electron/apps

Demo

See electron-algolia.herokuapp.com

Development

Try it out locally:

git clone https://github.com/electron/algolia-indices
cd algolia-indices
npm install
npm test
npm start

License

MIT

algolia-indices's Issues

Create an index for Electron glossary terms

Electron has a glossary at https://github.com/electron/electron/blob/master/docs/glossary.md

These terms are parsed by electron/i18n and exported by the electron-i18n module:

> require('electron-i18n').glossary['en-US']
{ ASAR: 
   { term: 'ASAR',
     description: 'ASAR stands for Atom Shell Archive Format. An asar archive is a simple tar-like format that concatenates files into a single file. Electron can read arbitrary files from it without unpacking the whole file.' },
  Brightray: 
   { term: 'Brightray',
     description: 'Brightray was a static library that made libchromiumcontent easier to use in applications. It is now deprecated and has been merged into Electron\'s codebase.' },
  CRT: 
   { term: 'CRT',
     description: 'The C Run-time Library (CRT) is the part of the C++ Standard Library that incorporates the ISO C99 standard library. The Visual C++ libraries that implement the CRT support native code development, and both mixed native and managed code, and pure managed code for .NET development.' },

It would be useful to display these glossary results when people search on electronjs.org

Enable advanced syntax

generate key-value searchable content

Via @MarshallOfSound in electron/electronjs.org-old#1248 (comment)

E.g. doc: to limit searches to just the API documentation or app: to search for apps 🤔

We can implement this by creating a string of metadata to attach to each record:

{
   name: 'foo',
  author: 'sue',
  meta: 'author:sue package:foo'
}

For docs:

{
  title: 'Updating Your App',
  slug: 'updating-your-app',
  meta: 'doc:updating-your-app doc:Updating Your App'
}

or

type:app

Remove dependency to `actions/npm`

Seems like this was removed a while ago:
https://github.community/t/builtin-actions-npm-is-missing/16499

https://github.com/actions/setup-node might be a possible lead.

isPackaged not available in search

Not sure what else from 3.0.0 is missing. If the value isn't found is there a server-side search this can post to?

Upload indices using Algolia client

Currently the indices are uploaded manually in the browser. Let's create a script that updates the index automatically.

const myIndex = apiClient.initIndex('contacts');
myIndex
  .addObject({
    firstname: 'Jimmie',
    lastname: 'Barninger',
    company: 'California Paint',
  })
  .then(content => console.log(content))
  .catch(err => console.error(err));

flaky tests - planned: Error: NA (plans must appear once in output)

See https://travis-ci.org/electron/algolia-indices/builds/538400821

PR: #55 - one check green, one red

/cc @BinaryMuse

Update indices automatically on a schedule

npm run update already exists. Just needs to be set up on Heroku.

• add http://github.com/zeke/github-buildpack
• create scheduler task

ipcMain events are missing from the index

Several methods exist: https://electronjs.org/docs/api/ipc-main#methods

But where are they?

Create standalone indices for each result type

In our call today with Algolia it was recommended that we create a separate index for each datatype. We can still search for all items across indices simultaneously using the technique outlined below.

Indices:

• apis
• tutorials
• packages
• repos
• apps

const search = instantsearch({
  appId: APP_ID,
  apiKey: API_KEY,
  indexName: INDEX_NAME_1
  searchFunction: (helper) => {
    // Grab current query from main search instance
    var query = search.helper.state.query;

    // Set query for 2nd index instance
    another_search_instance.helper.setQuery(query);

    // Send query for 2nd instance
    another_search_instance.helper.search();

    // Send query for main search instance
    helper.search();
  }
});


var another_search_instance = instantsearch({
  appId: APP_ID,
  apiKey: API_KEY,
  indexName: INDEX_NAME_2
});

Add an a tl;dr description for tutorials (guides) indices

Currently it's not possible to preview the short description of the page using search, not on dotorg nor Electron Discord. It's would be good to take the first paragraph which describe the content of page, and put thhem into tldr field.

platform strings are missing from API URLs

https://electronjs.org/docs/api/browser-window#winsetclosableclosable

should be

https://electronjs.org/docs/api/browser-window#winsetclosableclosable-macos-windows

Ensure algolia indices do not contain old data

npm run upload updates the indices. If the objectID of a give record already exists, it will be overwritten. That's what we want. But if the objectID is changed for some reason, the old data will not be replaced and the index will contain 2 results for the same record. A few ways we can prevent this:

• clear the whole index each time before uploading

or

• keep track of objectIDs somehow and clean up after the uploader

Create an index for repos that depend on Electron

https://github.com/electron/repos has a buncha data about GitHub repos that depend on Electron. Let's build an Algolia index for it here.

Fix method slugs to match GitHub-style slugs

https://electronjs.org/docs/api/web-request#web-requestonheadersreceived

... should be ...

https://electronjs.org/docs/api/web-request#webrequestonheadersreceivedfilter-listener

dock-related methods are missing from the index

• app.dock.downloadFinished(filePath)
• app.dock.hide()
• app.dock.setBadge(text)

https://electronjs.org/docs/api/app#appdockbouncetype-macos

etc...

Prevent double-periods add the end of TLDR properties

Create a custom objectID for each entry

https://www.algolia.com/doc/guides/indexing/structuring-your-data/#unique-identifier---objectid

If you don’t provide one, Algolia will generate one automatically. However, it will be easier to remove or update records if you have stored a unique identifier in the objectID attribute.

If your objects have unique IDs and you would like to use them to make future updates easier, you can specify the objectID in the records you push to Algolia. The value you provide for objectIDs can be an integer or a string.

Examples:

• api-{{api.fullSignature}}
• tutorial-{{tutorial.slug}}
• package-{{package.name}}
• repo-{{repo.fullName
• app-{{app.slug}}

API URLs often have wrong anchor

Currently there are many cases of the #.... part of the URL in the API not being correct. For properties it's including the API name at the start, for instance properties there's sometimes a shortened name used for the signature (in Session it uses sess.<instanceproperty>, some properties are marked readonly which ends up in the URL anchor, etc.

All of these might be able to be fixed in the current code, but it brings up the question of whether using electron-api.json as the data source is the best method. It's a layer removed from the docs themselves, and so it loses information needed to accurately reconstruct URLs. It seems like it will always be at risk of having incorrect URLs as a result. It's not the end of the world for the URLs not to jump to the correct part of the page in the docs, but it does limit the usefulness.

Possible more robust solutions could be to have electron/docs-parser put websiteUrl on properties, methods, events, etc, or for this code to parse the docs directly like electron/docs-parser so that it has all the information available for accurate URLs.