1

I have a python project that i am documenting with sphinx. The project reads in an xml configuration file. What is the best way to document this configuration file? Can i include an xml schema somehow? Or have a nice cascaded example? I know i can just type it out, but is there a better way to make it look pretty and easy to write/maintain?

All i have found is ways to include xml in the sphinx to change the structure etc.

I am looking for a way which is highly integrated and easy to use.

Thanks :D

bad_coder
  • 11,289
  • 20
  • 44
  • 72
da_steve101
  • 283
  • 4
  • 16
  • question reworded here: https://stackoverflow.com/questions/49538195/sphinx-how-to-automatically-generate-documentation-from-xml-schema-xsd – Donatello Mar 28 '18 at 15:21

1 Answers1

0

The answer to this question recommends using Sphinx's literalinclude directive.

This will allow you to include the literal content of the XML file which you could document with standard XML comment strings <!-- -->. The directive allows you to specify the language of the content which presumably affects final rendering.

Community
  • 1
  • 1
Mark Streatfield
  • 3,189
  • 1
  • 22
  • 19
  • yeah i saw that. That is just the text method though. Im kind of envisioning a nice expandable xml tags ... but i have been looking and i can't find anything else :/ but thanks :D – da_steve101 Jan 24 '14 at 01:57
  • 1
    I think the alternative would be to write a new domain for Sphinx (http://sphinx-doc.org/domains.html) which allows it to parse the XML in a more native manner. – Mark Streatfield Jan 24 '14 at 02:08
  • Or rather, a domain for the DTD that defines the schema. – Mark Streatfield Jan 24 '14 at 02:29
  • Thats actually a great idea, but i only have two configuration files in this project so probably not worth it :/ but next time :D – da_steve101 Jan 24 '14 at 02:49