NDS for Programmers
This is the beginning to the top-down documentation for NDS. Though there are comments in the source files, this document is intended to bring those together.
Summary of tech stack
The following things are required to get NDS running on its own
- Python 3.9
- Flask (the web framework)
- Jinja template engine
- lxml
Outside of this, you may want to run NDS with a web server such as apache or nginx.
Project dependencies and Makefile stuff
- saxon9.jar
- xmllint
How lookups work
FST - Lexicon connections
extending lookups and generation
Rendering: the template system
The reader plugin / bookmarklet
Development environment, and how to debug / test locally
Will elaborate later, but, wihin the nds-reader directory, I have been
running python -m SimpleHTTPServer in one terminal, make rebuild on
changes in another. Then I go to the test html pages at localhost:8000/
A handy tool for running a command while watching for code changes is pywatch
If there is something that doesn’t work within the test html files, you can
also add a make bookmarklet-install, and then run the NDS server locally,
go to the read/ page and click the button. This is less ideal because less
debugging options will be available.
TODO: write more, but for now, collecting notes and ideas while they are fresh
SSL / HTTPS considerations
In order for the reader to work over SSL, on Facebook and Wikipedia, some sneakiness was required, because the resources couldn’t simply be served for all projects on gtweb in the same way as projects on gtoahpa. The SSL certificate we have is only good for one subdomain, thus the easiest way was to get other projects to use this subdomain instead.
This solution requires two parts:
- Configuration information in NDS that will point the reader to the SSL subdomain when it downloads the required JS and CSS files; and also to point the reader at the SSL domain when making dictionary API requests. Following is a snippet of the YAML config for the project kyv:
ReaderConfig:
Settings:
# host path without scheme (https, http) to reader lookup API, no trailing
# slash.
api_host: "sanit.oahpa.no/reader/kyv"
# URL to serve media from, minus scheme, and no trailing slash.
media_host: "sanit.oahpa.no"
2.) A setup within nginx to allow proxying of specific requests to the non-SSL projects via the SSL project. This is left to the reader with admin access to inspect nginx config files, I will not paste them here for sikkerhets skyld.
Debugging
Logging
TODO: sprinkle some debug log statements throughout the code