square
Environment variable interpolation
To get the right documentation published on different deploy contexts (i.e. both on staging environment and production environment) it would be very useful to be able to use environment variables inside fdoc.
In particular, it would be nice to be able to write something like this:
# my_service.fdoc.service
...
basePath: $env['CURRENT_ENV_BASE_PATH']/v1
...
So that when the documentation gets generated (deploy time), the right URL gets generated too into documentation.
One thing I've done for our internal fdoc documentation generation here is ERB the .fdoc.service file. I suspect you already have a script running to kick off the HTML generation, what about adding a pre-process step there?
You are right: I already have a rake task that is invoked at deploy time to generate the HTML generation and it does something like this:
...
`fdoc convert #{file} --output=#{dest} --url-base-path=#{ENV['API_WEB_SERVER']}/docs --templates=#{template}`
...
the problem here is that - due to issue #52 - the --url-base-path option seems to get ignored by fdoc convert command.
Of course I could do something like pre-processing all .fdoc files in order to change each basePath value, but it would be quite tricky, doesn't it?
The ERB preprocessing of .fdoc.service files you've already done for your internal doc might be become a feature, isn't it?
It will be sufficient to close this issue if I were able to write something like this:
# my_service.fdoc.service
...
basePath: <%= env['CURRENT_ENV_BASE_PATH'] %>/v1
...