docarchive can't be rendered with local python web server

Question

cctile OP

Created Jun ’21

Replies 2

Boosts 0

Views 1.9k

Participants 3

Exported a docarchive. Then at command line, went into the directory and ran

$ python3 -m http.server

to start local web server. Pointing Safari 14.1.1 at the address http://localhost:8000/index.html and I see error message "The page you’re looking for can’t be found."

Any guidance?

Answered by slzh in 678313022

Currently (Beta 1) you can't use an entirely static file host to serve a .doccarchive.

You need to host it like described in the session Host and automate your DocC documentation

The example there is for an Apache .htaccess file — but in general the single page application contained in the archive seems to expect the following:

it will be served from a path starting with /documentation/<moduleName> or /tutorials/<moduleName> (if you browse to /documentation/ only it will show the message "The page you’re looking for can’t be found.")
it is served from the server root because all links are relative to the server root and resources (CSS, JS) are also looked up from there.

I've filed FB9153714 to ask for an option to at least allow a prefix to be specified.

A fully static version may be nicer — but it could limit the functionality that can be offered like search.

Boost

Answer 1

slzh OP

Jun ’21

Recommended

Currently (Beta 1) you can't use an entirely static file host to serve a .doccarchive.

You need to host it like described in the session Host and automate your DocC documentation

The example there is for an Apache .htaccess file — but in general the single page application contained in the archive seems to expect the following:

it will be served from a path starting with /documentation/<moduleName> or /tutorials/<moduleName> (if you browse to /documentation/ only it will show the message "The page you’re looking for can’t be found.")
it is served from the server root because all links are relative to the server root and resources (CSS, JS) are also looked up from there.

I've filed FB9153714 to ask for an option to at least allow a prefix to be specified.

A fully static version may be nicer — but it could limit the functionality that can be offered like search.

1

Answer 2

roblabs OP

Jun ’21

If you check the video for Host and automate your DocC documentation, the discussion on Apache says that your web server should be able to customize requests including how to route them. Search the transcript for Vue.js web app. Quote from the transcript:

if the request starts with /documentation/ or /tutorials/ then the server should respond with the index.html file that's located in the documentation archive

There is a Node server, called serve that does just that. Using this server, I was able to locally host documentation & tutorials.

# using https://www.npmjs.com/package/serve
serve -h | grep requests
#      -s, --single                        Rewrite all not-found requests to `index.html`

My example usage for SlothCreator:

# Build
# path to Xcode 13 Beta, adjust when its out of Beta
#   having a known output builder folder is helpful when searching for the output
/Applications/Xcode-beta.app/Contents/Developer/usr/bin/xcodebuild \
  docbuild \
  -scheme "SlothCreator" \
  -derivedDataPath tmp/derivedDataPath

# Serve
# Find the Doc Archive, 
#   then serve over port 4001 using https://www.npmjs.com/package/serve
find tmp/derivedDataPath \
  -name "*.doccarchive" \
  -exec serve --listen 4001 --single {} \;

# open in Safari
open http://localhost:4001/documentation/SlothCreator
open http://localhost:4001/tutorials/SlothCreator

Bonus: would be nice to have this served over GitHub Pages

1