generate docs for api.oxen.io

[majestrate]

we should make a util that will spit out markdown for api.oxen.io for lokinet's config options and the zmq rpc api.

[majestrate]

we have programmatic comments in our config gen as well as other hints about usage, thinking we make an executable that:

• spits out a list of all config sections
• given a section, print a high level description of the section
• given a section list all option names
• given a section and option print out markdown text for documentation on it.

then you can do something like:

for sect in $( docgen sections ) ; do
  for opt in $( docgen opts $sect ) ; do
    docgen markdown $sect $opt 
  done
done > lokinet.md

[majestrate]

or... it could just spit out all the docs

[N-NeelPatel]

@majestrate - can I work on this to generate docs using commands?

[majestrate]

go ahead

[N-NeelPatel]

@majestrate - I created a shell script according to the points you mentioned above. Do you think it is workable? let me know what you think.

#!/bin/bash

config_file="path/to/config_file.conf"  # Replace with the actual path to your config file

list_sections() {
    grep -E "^\[[^\]]+\]" "$config_file" | sed 's/\[\(.*\)\]/\1/'
}

describe_section() {
    section="$1"
    description=$(grep -A 1 -e "^\[$section\]" "$config_file" | tail -n 1 | sed 's/# *//')
    echo "$description"
}

list_options() {
    section="$1"
    awk -F "=" "/^\[$section\]/,/^(\[.*\]|$)/ { if (\$1 ~ /^[a-zA-Z_][a-zA-Z0-9_]*$/) print \$1 }" "$config_file"
}

generate_documentation() {
    section="$1"
    option="$2"
    documentation=$(grep -A 1 -e "^\[$section\]" "$config_file" | grep -A 1 -e "^[[:space:]]*$option[[:space:]]*=")
    echo "$documentation"
}

for sect in $(list_sections); do
    for opt in $(list_options "$sect"); do
        generate_documentation "$sect" "$opt"
    done
done > lokinet.md

[majestrate]

On Tuesday, 23 May 2023 01:13:03 EDT Neel Patel wrote:

@majestrate - I created a shell script according to the steps you mentioned above. Do you think it is workable, let me know what you think?

I do appreciate the initiative but this wasn't exactly what i had in mind. i dont think i properly articulated the underlying task in this issue, this is my bad. i'll try to rephrase this in a much more concise way so that it's unambiguous on what i am looking for here.

inside lokinet, we have a zmq rpc server with a bunch of endpoints that you can call. these endpoints do various bits and bobs and they are at the moment 100% undocumented (this code lives in the directory llarp/rpc/ under the llarp::rpc namespace ). we recently redid how we defined those endpoints in the code so that they are highly structured now. our ini config generation code is highly structured too but that config code lets us attach comments to these generated config options, and has a lot of other metadata tags relevant to the underlying functionality, e.g. client only option, required option, deprecated option, options which take multiple values.

what i am looking for is to add that kind of documentation / comments into the structured definitions of our znq rpc endpoints so that we can have an seperate c++ executable which output markdown docs of our rpc endpoints. this would be very constexpr heavy C++ code so that this metadata is omitted when compiling lokinet itself but not when compiling this new executable that outputs markdown.

in oxen-core we have a python script that parses comment blocks. that feels a bit hacky and the approach in our config subsystem feels like a much nicer way to present the data. since the primary consumer of this is the api.oxen.io documentation page and anyone extending this would already be balls deep in the internals anyways, expecting them to not feel alienated by moving about in C++ isn't an unreasonable constraint. additionally we could eventually use this to springboard into unit tests for that part of the code, or maybe even an entry point into proper integration tests. lots of future directions this can go in, but the first thing that happens is the initial work to add the foundation for that.

-- ~jeff

[majestrate]

nevermind, we have not merged in the rpc refactor yet so that would need to be figure out first... hmmm.

[N-NeelPatel]

So this won't be done until rpc refactor is merged?

[majestrate]

yes correct