I would like to generate documentation for a kRPC service. I found docgen tool but there were no instructions how to use it, and I ended up with the error below. The current directory is the service with C# classes.

> krpc-docgen java . order.txt java/
Traceback (most recent call last):
  File "C:\Program Files\Python37\Scripts\krpc-docgen-script.py", line 11, in <module>
    load_entry_point('krpctools==0.4.7', 'console_scripts', 'krpc-docgen')()
  File "c:\program files\python37\lib\site-packages\krpctools\docgen\__init__.py", line 59, in main
    macros = resource_filename(__name__, '%s.tmpl' % args.language) \
AttributeError: 'str' object has no attribute 'decode'

How to use it correctly? Does it generate .rst files which can be used with Sphinx or only documentation for IDE (such as javadoc)?

So, after a few more attempts, here are my observations:

• Python 3 is not supported by krpc-docgen, see __init__.py:59 and this answer (I installed Python 2.7)
• krpc-servicedefs requires additional argument -o <json_output_path> or it will print the ouput to the console

...but I need help with the last issue:

Traceback (most recent call last):
  File "F:\Python27\Scripts\krpc-docgen-script.py", line 11, in <module>
    load_entry_point('krpctools==0.4.7', 'console_scripts', 'krpc-docgen')()
  File "f:\python27\lib\site-packages\krpctools\docgen\__init__.py", line 111, in main
    content, documented = process_file(domain, services, args.source)
  File "f:\python27\lib\site-packages\krpctools\docgen\__init__.py", line 171, in process_file
    content = template.render(context)
  File "f:\python27\lib\site-packages\jinja2\environment.py", line 1008, in render
    return self.environment.handle_exception(exc_info, True)
  File "f:\python27\lib\site-packages\jinja2\environment.py", line 780, in handle_exception
    reraise(exc_type, exc_value, tb)
  File "./mechjeb.tmpl", line 4, in top-level template code
    {% import domain.macros as macros with context %}
  File "f:\python27\lib\site-packages\jinja2\loaders.py", line 168, in get_source
    pieces = split_template_path(template)
  File "f:\python27\lib\site-packages\jinja2\loaders.py", line 31, in split_template_path
    raise TemplateNotFound(template)
jinja2.exceptions.TemplateNotFound: f:\python27\lib\site-packages\krpctools\docgen\java.tmpl

The file is physically there. I copied SpaceCenter template and changed service and enumeration names.

I think this might be caused by line 130 in docgen/__init__.py The search paths are set to ./ (the current directory) and / (top level directory on Linux). But you appear to be on windows so maybe something needs to be added here - maybe try adding 'F:' to the list?

I think this might affect it too: pallets/jinja#767 Apparently the paths passed to jinja need to contain slashes only, never backslashes.

I spent an hour debugging it and it is caused by the issue you mentioned.

The problem is that the path is absolute. Jinja splits the path to pieces but it is combined incorrectly, omitting the slash after the drive letter - f:python27\lib\site-packages\krpctools\docgen\java.tmpl. This is an issue of Jinja (at least under Python 2.7). However, for docgen to work correctly on Windows, it is necessary to replace backslashes with forward slashes in __init__.py:59 with replace('\\', '/').

The good thing is that, after I made those modifications, it created a .rst file. :-)

Great job! :-) I've just tried your latest changes and it works even without my workaround in Jinja's code. I will let you know if there are other issues.

It does indeed generate an Sphinx .rst file. When calling krpc-docgen, the arguments are as follows:

• The first argument is the language,
• the second is the path to a template file (which looks like this) which allows you to specify which class you want to generate documentation for and allows you to add a header/footer/whatever you want to the output,
• the third argument is a file which specifies how to order methods/properties in the generated rst (for example like this),
• the fourth argument is a path of where to write the output .rst file to,
• the remaining arguments are paths to the "service definition files" that contain information about the things you are trying to document. These files are generated from the compiled C# assembly for your service using another tool, called krpc-servicedefs

To generate a service definition file, you can call krpc-servicedefs with the following arguments:

• the first is the path to your copy of Kerbal Space Program
• the second argument is the name of your service, e.g. SpaceCenter
• the remaining arguments are the paths to the assemblies needed to load your service. For these you would need probably need the path to KRPC.dll and the DLL for your service.

This tool hasn't really been polished for use by others, so there might be bugs... Please let me know if something doesn't work.

Two more issues with Python 3:

• print is missing parentheses in __init__.py:87
• __init__.py:104: AttributeError: 'dict' object has no attribute 'iteritems'. Solution: change iteritems() to items(); see StackOverflow answer.

So, it successfully generated the .rst file but the file does not have XML comments which I put in my code. Do I need to copy those comments manually or am I missing something?

//EDIT: Now it works, I just needed to enable XML output in my VS build settings.

Cool - I'll get those python 3 issues fixed.

How can I add a new line to my documentation? I would use <para /> but it doesn't work. Neither <br /> nor <p> does.

  File "c:\program files\python37\lib\site-packages\krpctools\docgen\docgen.py", line 59, in _generate_node
    raise RuntimeError('Unknown node \'%s\'' % node.tag)
RuntimeError: Unknown node 'para'

You should be able to do this by just including a blank line, for example:

    /// <summary>
    /// First line of text.
    ///
    /// Another line of text.
    /// </summary>
    public void MyMethod ...

I'm using classes from the SpaceCenter service. What do I need to do to link them with kRPC documentation?

For example, I have a method SpaceCenter.Node makeNode() and I want to link SpaceCenter.Node to kRPC Node.

//EDIT: Would you mind updating https://github.com/djungelorm/sphinx-lua/ as well? iteritems() needs to be replaced by items(); that's all.

Generating links like that isn't possible currently. Will see if I can get it added though.

And yep, I'll update sphinx-lua - thanks for spotting another bug!

Finally done! :) https://genhis.github.io/KRPC.MechJeb/

Would you please add my service to the kRPC website?

Btw. I can submit a PR with a tutorial if someone else wanted to generate their own documentation. Shall I do that?

Awesome - I'll get that link added. Sorry for not seeing your forum post about adding a link ages ago... not sure how I missed it.

And a tutorial on docgen would be great!