Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Figure out how to generate slice documentation in the future #75

Open
Kissaki opened this issue Oct 27, 2019 · 0 comments
Open

Figure out how to generate slice documentation in the future #75

Kissaki opened this issue Oct 27, 2019 · 0 comments
Labels
decision A decision needs to be made within this issue

Comments

@Kissaki
Copy link
Member

Kissaki commented Oct 27, 2019

Our generated slice documentation has always been a very simple html file structure.

Ice 3.6 still contains the slice2html executable. Ice 3.7 does not and tells you to use doxygen, which supports slice.

See v3.6-Usingslice2html and v3.7 Using Doxygen for Slice Documentation.

The doxygen generated HTML documentation is a lot more complex and IMHO overkill, and reduces readability and discoverability instead of improving it.

We should explore and decide on how we want to handle this in the future. Possibly establish a (documented or automated) generation workflow.

Ice has moved from slice file and dynamic type usage to generated code for more languages (namely PHP as well). Arguably, the generated types are enough with a decent IDE. Although being able to link to types and read them without generated code available would be very useful at times.

This issue became apparent in #60.
@Kissaki Kissaki added the decision A decision needs to be made within this issue label Oct 27, 2019
Kissaki added a commit that referenced this issue Oct 27, 2019
@Kissaki
Slice: Add generated slice HTML documentation 1.2.0, 1.2.7, 1.3.0
db4d751 
Up to now we host our slice documentation on http://mumble.sourceforge.net/slice/.

However, having this additional host and service separately makes no sense
other than for historic reasons; keeping the old URLs in tact.

With more documentation moving to the website, it makes sense to integrate
the slice documentation into the website as well.

1.2.19 still has the same slice definition as 1.2.7, so no generating
necessary for that.
The old site on mumble.sf.net also hosts the generated HTML for 1.2.0,
1.2.7 and (snapshot) 1.3.0.
The 1.3.0 content added here is definitely of stable version 1.3.0.

Fixes #60

This documentation is generated with slice2html from Ice 3.6. Ice 3.7 no
longer provides this binary, and instead refers to doxygen which
generates complexer HTML. This means we will have to evaluate and
decide on how we want to handle this in the future. See #75.
@Kissaki Kissaki mentioned this issue Oct 27, 2019
Merged
@Kissaki Kissaki mentioned this issue Jan 15, 2020
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
decision A decision needs to be made within this issue
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
1 participant
@Kissaki