make_instructions.txt

#################
MAKE INSTRUCTIONS
#################

Contents:

    Overview

    Setup
    
    FAQ
    
    Available targets

################################################################################

Overview

    The functions found in this makefile are associated with the Algolia search
    indices which provide search functionality on Plotly's documentation pages.

    We have multiple search indices:
        - js_docs (https://www.algolia.com/apps/7EK9KHJW8M/explorer/browse/js_docs)
            - Search on: https://plotly.com/javascript/
            - Includes html files found in documentation/_posts/javascript
            - Update by running `make update_js_search` locally from the root of
              the documentation repo
        - python_docs (https://www.algolia.com/apps/7EK9KHJW8M/explorer/browse/python_docs)
            - Search on: https://plotly.com/python/ and https://plotly.com/pandas/ 
            - Includes html files found in documentation/_posts/python
            - Update by running `make update_python_search` locally from the root of
              the documentation repo
        - r_docs (https://www.algolia.com/apps/7EK9KHJW8M/explorer/browse/r_docs)
            - Search on: https://plotly.com/r/ and https://plotly.com/ggplot2/ 
            - Includes md files found in documentation/_posts/r and 
              documentation/_posts/ggplot2
            - Update by running `make update_r_search` locally from the root of
              the documentation repo
        - schema (https://www.algolia.com/apps/7EK9KHJW8M/explorer/browse/schema)
            - Search on chart attribute reference pages
              (i.e.: https://plotly.com/javascript/reference,
               https://plotly.com/matlab/reference, https://plotly.com/python/reference
               https://plotly.com/r/reference) 
            - Includes all schema from plotly.js (https://api.plot.ly/v2/plot-schema)
            - Update by running `make update_ref_search` locally from the root of
              the documentation repo

################################################################################

################################################################################

Setup

    In order to update the indices you will need to have Ruby and Jekyll
    installed. For more information on setting up these tools see our
    documentation contributing guide:
    https://github.com/plotly/graphing-library-docs/blob/master/Contributing.md
    Additionally, you will need to set the Algolia API KEY as an environment
    variable on your local machine. This key should remain private, please
    contact chelsea@plot.ly for the key or more information.

################################################################################

################################################################################

FAQ

    How to Update: 
        You can update the index of your choice by running the available target
        functions (for example: `make update_python_search`) listed below from
        the root of the documentation repo (i.e. the same path as this file). 
    
    When to Update:
        The search index should be updated when a new doc is added to the associated 
        directory (i.e. run `make update_python_search` when adding a NEW html file 
        to documentation/_posts/python.) The schema index should be updated when a 
        new plotly.js version is added to streambed. 
    
    How to Exclude Files from the Search Index:
        Each search index has an associated _config.yml (i.e. _config_js_search.yml,
        _config_python_search.yml, _config_r_search.yml). In the associated .yml file
        under algolia there is a list of excluded files. You can add any files or paths
        that should not be included in the search to that list.
    
################################################################################

################################################################################

Available targets (i.e. $ make target):

    search_readme -> `less` this file

    update_js_search -> update the plotly.js search index: https://www.algolia.com/apps/7EK9KHJW8M/explorer/browse/js_docs

    update_python_search -> update the python search index: https://www.algolia.com/apps/7EK9KHJW8M/explorer/browse/python_docs

    update_r_search -> update the r search index: https://www.algolia.com/apps/7EK9KHJW8M/explorer/browse/r_docs
    
    update_ref_search -> update the schema search index: https://www.algolia.com/apps/7EK9KHJW8M/explorer/browse/schema

################################################################################