opendap/documentation

OPeNDAP AsciiDoc site

Quick Start

The QuickStart Guide (PDF) provides a overview of our software and its use

User Guide

The UserGuide (PDF) provides general information about the OPeNDAP software, the two versions of the Data Access Protocol (DAP) and information about access to remote data made available using DAP.

Data Access Tutorials

The Data Access Tutorials show how to use various software clients to access data using the DAP web API.

Client Authentication

Many institutions now require that you (or more accurately, your software client) must authenticate before access to data will be permitted. This is notably true for all NASA assets: Authentication is required for data access.

• You can learn about DAP Client Software Authentication here.

• You can learn about how to use NASA’s EDL tokens for Client Software Authentication here.

Hyrax Installation and Configuration Guide

The Hyrax Installation and Configuration Guide (PDF) provides information about the Hyrax Data Server. In this guide you will find a description of the server’s featrues and all of its configuration parameters. Also described in teh guide are other web services that Hyrax provides, including WMS and WCS.

Libdap library documentation

The libdap library documentation provides reference information for our implementation of DAP2 and DAP4.

BES data server framework

The Back End Server (BES) is the modular framework used to build the data access and manipulation layer of the Hyrax data server.

Notes about this repository

Building CommonMark from AsciiDoc

Quick note about coverting to CommonMark Markdown from AsciiDoc.

To convert to CM from adoc, use 'asciidoctor' and 'pandoc' like this:

asciidoctor -b docbook5 -o quick_start_hack QuickStart.adoc
pandoc -f docbook -t commonmark -o quick_start.cm quick_start_hack

About opendap.github.io/documentation/

The https://opendap.github.io/documentation/ site is populated with HTML and PDF documents that are automatically built any time an AsciiDoc file in the documentation repo is updated on the master branch.

This page comes from the github.com/OPeNDAP/documentation repository, but it contains links to other pages from other OPeNDAP github documentation repositories (e.g., hyrax\_guide). To add new documention from a new repo, first arrange to publish its content via gh-pages and github.io and then link those pages here. See the github.com/OPeNDAP/hyrax_guide repo and the entry above for Master_Hyrax_Guide.html/pdf for an example.

Automatic github.io updates

See Convert AsciiDoc to HTML/PDF & publish to GitHub Pages with Travis CI and Asciidoctor Docker containers for the low-down on how the automatic updates work.

Another take on the same sort of process - updating gh-pages from a .travis.yml file - that does not use asciidoctor: Automatically Update GitHub Pages with Travis.

documentation's Issues

Travis CI Authentication fails when building documentation

The last two PRs on OPeNDAP's documentation failed with the following error in the logs:

$ git push --force --quiet "https://${GIT_UID}:${GIT_TOKEN}@github.com/OPENDAP/documentation" master:gh-pages
remote: Invalid username or password.
fatal: Authentication failed for 'https://github.com/OPENDAP/documentation/'

You can see the logs on the Travis CI for Build #306 and Build #307. You can also find them from the Build history .

BTW: the errors take place towards the end of the logs around lines > 1260. Build 306 was trigger by the merger of my PR #18, where Build 307 was trigger by the merger of PR #16

FYI: The last successful build was build #305, 7 months ago.

typo in tutorials when using pydap+EDL tokens to access data

In the file tutorials/ClientAuthenticationWithEDLTokens.adoc , in the 3.3 pydap subsection it should read:

my_session.headers={"Authorization": auth_hdr}

otherwise you get

HTTPError: 401 Unauthorized
HTTP Basic: Access denied.

see this pydap/issue#302.
Will get a PR next

add tutorial with OPeNDAP + bokeh for interactive visualization of 4D datasets

I just found out about bokodapviewer --a really cool python application developed using bokeh - to interactively visualize data hosted on OPeNDAP servers. I think we should include it in the documentation - tutorials. I tried it out and it still works with very minor tweaks! Installation works well via pip.

Here is the original youtube video tutorial, and an updated one in 2020 using HyCOM data.

broken hyperlinks referencing subset data

The Constraint Expressions part of the Documentation has some broken links. These are very easy to fix, but I wanted to open this issue to:

1. Understand the broken links to make the proper modifications.
2. Raise an issue so that a PR can be connected to it.

With regards to 1)

Below is one of the broken links in the documentation. The broken hyperlinks under Constraint Expressions all share the similar behavior. The hyperlink refers to the test data http://test.opendap.org/opendap/data/nc/sst.mnmean.nc.gz?sst[3][4][5] (DAP2)

documentation/UserGuideComprehensive.html

Line 2335 in 6ab6ebb

<p>&#8230;&#8203;/nc/sst.mnmean.nc.gz?sst[3][4][5] <a href="http://test.opendap.org/dap/data/nc/sst.mnmean.nc.gz.asc?sst%5B3%5D%5B4%5D%5B5%5D">Click here for sample output.</a></p>

The url has already been escaped, but the link fails to open on the browser with a header that says

Hyrax - Resource Not Found (404). 

I noticed that the file type is asc (non-structure ASCII). Without the asc the hyper link downloads the data.

a) Is the goal to open an ASCII type file on the browser to visualize the stream of numbers?
b) Is the goal to download data (any format)?
c) Should the proper link be a DDS, something like this?

Whether a, b or c), will inform me on how to proceed to fix these hyperlinks and submit a PR.