Documentation XML raw data

[Josh]

If you want to experiment with auto-generated HTML, PDFs, eBooks, or whatever, here are some raw data files I am working with for the new documentation system:

http://www.leadwerks.com/documentation/toc.xml

http://www.leadwerks.com/documentation/API-Reference_Object_Entity_SetPosition.xml

 

The structure of these will probably not change much. Let me know if you come up with anything cool.

[martyj]

I'd recommend you split up parameters like this.

<parameters>
<x>
 X component of the specified position.
</x>
<y>
 Y component of the specified position.
</y>
<z>
 Z component of the specified position.
</z>
<position>
 the position to set.
</position>
<global>
 indicates whether the position should be set in global or local space.
</global>
</parameters>

 

Would allow for more flexible documentation. If I have some pare time I'll try to throw together a simple Bootstrap/Angular Material example together.

[Josh]

Does the PHP XML loader guarantee that the contents of <parameters> will be returned in their original order, and not alphabetized or something?

[martyj]

I'm 98% sure it will be in the original order and not alphabetized.

 

Imagine HTML sorting child elements by name and not order. Would be impossible to style things (Unless you flex).

[martyj]

I still have a lot more work to do on this, but here is what I have so far on a documentation app.

 

http://martyj.net/LEDocs/

 

I'm planning on making it fully offline as I've wanted offline docs since forever.

 

Things left to do:

• Style page better
  
• Parse XML to Javascript Objects
  
• Generate NAV based upon XML
  
• Support Page Changing with Nav
  
• Load XML when you change the page
  

[Rick]

I would think this might be a good case for nw.js? Store the information locally but do a check for update process with it to call an API to get the updated data? Controlled web environment so you know it'll look the same for everyone vs browser of the week. Just a thought.

[martyj]

@Josh is the only XML page http://www.leadwerks.com/documentation/API-Reference_Object_Entity_SetPosition.xml ?

 

If not, how do we access it via the info provided in toc.xml?

[Josh]

1) Yes 2) you can't.

[martyj]

I've updated my documentation demo here: http://martyj.net/LEDocs/

 

I don't think I can do much more on it as far as usability goes until more XML gets released. Right now everything is hard-coded JS objects.

 

I'd totally love to finish this project as I'd really want offline documentation.

 

Let me know if you want the source.

[Josh]

I added the Entity::SetPosition command to the TOC along with a file name for the data.

[martyj]

I have updated the link again. It will allow you to navigate to the SetPosition page. This parses the toc.xml to generate the navigation menu and parses API-Reference_Object_Entity_SetPosition.xml for the specific page.

 

The downsides:

 

Due to CORS issues, all the XML files have to be on the same host (or localhost). So to update it, I'll have to download the XML files.

[Josh]

What's the problem? I load XML files from the Steam servers all the time in PHP.

 

  function LoadXML($path)

{

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $path);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$content = @curl_exec($ch);

curl_close($ch);

 

//$content = @file_get_contents($path);

if ($content==NULL)

{

if ($_GET['debug']==1) { echo('Error: Load XML failed.'); }

return NULL;

}

$content = utf8_encode($content);

$content = str_replace(chr(11),'',$content);

$content = str_replace(chr(28),'',$content);

$content = str_replace(chr(25),'',$content);

if (trim($content=='')) return NULL;

return simplexml_load_string($content);

}

[Ma-Shell]

What's the problem? I load XML files from the Steam servers all the time in PHP.

 

The difference is that martyj uses js for loading and parsing the XML-files client-side, while PHP does that server-side.

CORS is a security mechanism implemented by browsers to prevent cross-origin-XSS.

[martyj]

What Ma-Shell said.

 

The nice aspect about this application is it can be deployed separately for 100% offline documentation.

 

Another nice aspect is that if you deploy the application say with version 4.4 of Leadwerks, the documentation matches the code. Kind of self-versioning.

 

I could try a JSONP request to pull down the documentation, the downside is it removes offline capabilities. We could also maybe use local storage to help with this as well.

[Rick]

I could try a JSONP request to pull down the documentation, the downside is it removes offline capabilities. We could also maybe use local storage to help with this as well.

 

Hence why I said maybe nw.js could be used for this. Still used offline with the ability to check if it can refresh it's data if online and download and save the updated files locally. Something plain html/css/js couldn't do very well. Using local storage wouldn't be ideal for this.

 

Not to mention that your environment is now stable and known for documentation. No screwing around coding for every web browser under the sun. You know how it looks on nw.js is how it'll look for everyone always. It's basically a better chm system because it allows you do code to pull changes when online but be able to still view it when offline.

[Josh]

A PDF generated from the online data would be nice. Anyone know how to create one?

[Ma-Shell]

It's far from perfect but I wrote a simple Python 3 - script which parses "API-Reference_Object_Entity_SetPosition.xml" (which has to be in the current directory) and exports it as HTML ("out.html") and LaTex ("out.tex"). You will need a LaTex-Compiler (e.g. https://miktex.org/download) to generate a pdf out of this LaTex-file.

generate_docu.py.txt

[Josh]

Cool! Here is my PHP code that displays docs.

docs.php