RFC: (Preliminary) API Documentation Now Online

A place to discuss everything related to Newton Dynamics.

Moderators: Sascha Willems, walaber

Re: RFC: (Preliminary) API Documentation Now Online

Postby Julio Jerez » Wed Oct 12, 2016 7:41 pm

Oh I see the source is there,
The source code for this exact build (mostly the modified Newton.cpp) is here:
https://github.com/olitheolix/newton-dy ... ree/sphinx


I see if I can merge tonight and commit it to the archive.
Julio Jerez
Moderator
Moderator
 
Posts: 12249
Joined: Sun Sep 14, 2003 2:18 pm
Location: Los Angeles

Re: RFC: (Preliminary) API Documentation Now Online

Postby oliver » Wed Oct 12, 2016 8:37 pm

Resolving the merge conflict and updating the PR is not the issue. I am just
not sure if I should volunteer more time towards Newton PRs since they
seem to always go unnoticed on GH :(
oliver
 
Posts: 36
Joined: Sat Sep 17, 2016 10:31 am

Re: RFC: (Preliminary) API Documentation Now Online

Postby Stucuk » Wed Oct 12, 2016 9:43 pm

oliver wrote:since they seem to always go unnoticed on GH :(

Just PM Julio or post on the forum.

----------------------------

Btw would it be possible for you to use commenting like NewtonDoc?
User avatar
Stucuk
 
Posts: 801
Joined: Sat Mar 12, 2005 3:54 pm
Location: Scotland

Re: RFC: (Preliminary) API Documentation Now Online

Postby Julio Jerez » Thu Oct 13, 2016 12:20 am

Ok I merged manually, it was not difficult at all.
I am sorry for overlooking that commit.
I think we can delete the pull request since it has conflict

This Is actually very very cool, now I can add more and more comments, and the engine can have was it always lacked.
Thank yo very much for the generous contribution.

Next time when you make a commit give a head start so that I do not work on those files until the they are integrated.

How do I get the docs, after I commit, I see a file ../C:\Development\newton-dynamics\doc\Doxyfile
but how do I open it?
is this like an online thing or a file that get downloaded when people sync?
Julio Jerez
Moderator
Moderator
 
Posts: 12249
Joined: Sun Sep 14, 2003 2:18 pm
Location: Los Angeles

Re: RFC: (Preliminary) API Documentation Now Online

Postby oliver » Thu Oct 13, 2016 4:02 am

Julio, is it possible that you do not receive GH notifications? You should get an email whenever someone creates a PR, or comments on an existing one.

If you do not get these emails, please check your GH settings: "Watch" (near the "fork" button) your repo, and check the fields in Settings->Notifications for your user. There is no need to announce PRs on a forum.

How do I get the docs, after I commit, I see a file ../C:\Development\newton-dynamics\doc\Doxyfile
but how do I open it?
is this like an online thing or a file that get downloaded when people sync?


Straight from https://newton-dynamics.readthedocs.io/ ... t/api.html :)
Code: Select all
doxygen Doxyfile
firefox html/index.html


This will build it locally (you will need to have Doxygen installed, obviously).

For the auto-generated online version you need to setup ReadTheDocs. I _may_ be able to do this for you, without write access to the repo, if you add the webhook as described here: https://docs.readthedocs.io/en/latest/webhooks.html
No guarantee that this works, but worth a shot (and you need the webhook anyway if you want that feature).

Yes, it is a pain... but almost there :)
oliver
 
Posts: 36
Joined: Sat Sep 17, 2016 10:31 am

Re: RFC: (Preliminary) API Documentation Now Online

Postby Stucuk » Thu Oct 13, 2016 2:23 pm

Stucuk wrote:Btw would it be possible for you to use commenting like NewtonDoc?

So thats a no then? So NewtonDoc project is officially dead if the comments are never going to use a system that information can be extracted so it can be formatted decently (Doxygen's format isn't great, hence NewtonDec's creation at the start of the year). The only thing that was missing previously was making the actual comment blocks doxygen compatible, new style gives no real definitions to what things are (Hence bad formatting).
User avatar
Stucuk
 
Posts: 801
Joined: Sat Mar 12, 2005 3:54 pm
Location: Scotland

Re: RFC: (Preliminary) API Documentation Now Online

Postby oliver » Thu Oct 13, 2016 5:57 pm

So thats a no then? So NewtonDoc project is officially dead if the comments are never going to use a system that information can be extracted so it can be formatted decently (Doxygen's format isn't great, hence NewtonDec's creation at the start of the year).


I don't know NewtonDoc, and could only find two mentions of it outside this thread.

new style gives no real definitions to what things are (Hence bad formatting)

What definitions and formatting are you talking about?
oliver
 
Posts: 36
Joined: Sat Sep 17, 2016 10:31 am

Re: RFC: (Preliminary) API Documentation Now Online

Postby Stucuk » Fri Oct 14, 2016 1:36 am

oliver wrote:I don't know NewtonDoc, and could only find two mentions of it outside this thread.

Thats because it was posted in the Secret "Developers" forum.

Stucuk wrote:Below is the Work In Progress version of NewtonDoc, an application i made which runs Doxygen to generate XML from the Newton Source and then it generates HTML documentation. Included in the Download is everything (Including some Newton source code) needed to make it work.

Double clicking on NewtonDoc.exe is all thats required. It will automatically update doxygenconfig.txt so that its Input/Output directories are where NewtonDoc.exe is currently located.

Newton Source code goes in the Source folder. Doc folder contains the HTML documentation. layout\l.css is copied at runtime to the Doc folder but the images are not.

- newtondoc_WIP_2016-03-11.rar

Note: Since this is the first time i have used Doxygen it is likely that some settings could be turned off. So the config file may not be optimal.

P.S When the first version is finished i will also release its source code (Its written in Delphi).



oliver wrote:What definitions and formatting are you talking about?

As in all doxygen generates is bland html outputs.

NewtonDoc is a custom parser which takes the XML output of Doxygen and generates custom HTML. The idea was to have documentation that was formatted decently rather than just generically like Doxygen does. Also for example allows custom features like having the function's deceleration in both C and Pascal, Hint boxes when hovering over links to show a extract of the functions description, etc.

Image
Image
User avatar
Stucuk
 
Posts: 801
Joined: Sat Mar 12, 2005 3:54 pm
Location: Scotland

Re: RFC: (Preliminary) API Documentation Now Online

Postby oliver » Fri Oct 14, 2016 7:19 am

This looks great!

The docu generator I use on RTD also ingests the Doxygen XML data to create the html pages. Is there a reason why NewtonDoc cannot use the very same XML data? I would have tried, but I don't use Windows.

Also, you should definitively release the source code, because you are not the only one who dislikes the default Doxygen look.
oliver
 
Posts: 36
Joined: Sat Sep 17, 2016 10:31 am

Re: RFC: (Preliminary) API Documentation Now Online

Postby Stucuk » Fri Oct 14, 2016 6:51 pm

oliver wrote:Is there a reason why NewtonDoc cannot use the very same XML data?

You have to read specific keywords to know what things are. Anything which isn't a doxygen special command (As in anything that doesn't have @ or \) is just treated as text with no actual way to tell what it is. Each line is split into <param> blocks. I was using "Desc:", "Remarks:", "Example:", "See Also:" to define what each line was so it could be parsed.

oliver wrote:I would have tried, but I don't use Windows.

Wine exists. Its a simple console application so wine should have no trouble.

P.S It also generates a pascal header for Newton as a byproduct (It doesn't convert Stucts as the union stuff isn't properly defined in the XML output, so some stuff still has to be done manually when it changes).
User avatar
Stucuk
 
Posts: 801
Joined: Sat Mar 12, 2005 3:54 pm
Location: Scotland

Previous

Return to General Discussion

Who is online

Users browsing this forum: No registered users and 27 guests