Version in javadoc links

mitm · December 16, 2019, 12:37am

The change to adding versions to the javadoc link breaks wiki links and should be returned to generic links.

Currently looks like,
https://javadoc.jmonkeyengine.org/v3.3.0-beta1/

should be,
http://javadoc.jmonkeyengine.org/com/jme3/

Otherwise every release requires an entire wiki redo.

Currently thats 32 links and 12 pages.

Edit: If this is not possible I can update the links but would be best not to.

Edit: I have to change them to https as it is but didnt know till now they were even changed.

RiccardoBlb · December 17, 2019, 9:09am

what about having a “latest” version?
EDIT:
done
https://javadoc.jmonkeyengine.org/latest/com/jme3/anim/tween/Tween.html

mitm · December 17, 2019, 2:59pm

To me, I think light background with dark text. Easier to read.

mitm · December 17, 2019, 3:01pm

The documentation page theme looks sharp btw.

RiccardoBlb · December 17, 2019, 3:02pm

Ok, this is another topic. I made it dark since the forum and the store have dark theme and i thought the home page was going to have it too. I think you can open a poll or something, honestly it’s the same for me.

github.com

jMonkeyEngine/javadoc.jmonkeyengine.org/blob/gh-pages/inject.css


/**
* Poor man's dark theme

@supports (filter:invert(1)){
    body{
        filter:invert(1);
        background-color:#2b2b2b;
    }
}
*/

This is the css that gets injected into the doc when it is generated.

mitm · December 17, 2019, 3:03pm

I see, latest version, I dont really care how its worded as long as its static.

pspeed · December 17, 2019, 3:05pm

Is “latest” master or is “latest” the last alpha/beta release?

RiccardoBlb · December 17, 2019, 3:06pm

Whatever is marked latest in github releases

pspeed · December 17, 2019, 3:08pm

Which I think means that even if we had a 3.3 final/stable release and someone cut a new 3.2.90 release that it would replace the 3.3 docs.

That’s probably not desirable.

jayfella · December 17, 2019, 3:08pm

I guess colors are highly opinionated, but from experience documentation should be light background dark text.

I like the forum colors but if I were the rule maker it would all be that way. Store, forum, docs, etc.

Either way, I do believe strongly that the documentation should be a light theme.

RiccardoBlb · December 17, 2019, 3:19pm

Yes you are right. So, how should we solve this now that the doc is updated automatically?
Maybe write some code to detect the higher version number (instead of using the github /latest api)?
Or have something in the wiki (eg. a property or a global variable (not sure what our wiki uses)) to update the links when there is a new release?

pspeed · December 17, 2019, 3:23pm

Do we build javadoc as part of the master builds?

Maybe just have the wiki point to that?

I don’t know what the process is so I can’t really comment. But in an ideal world, real releases would be marked as such and the docs would either be the latest release (version-wise) or just master.

Edit: and by “marked as such”, I mean that 3.2.5 would be under /3.2.5 and 3.3.0 would be /3.3.0… or if we don’t want to have a ton then just the latest from each branch.

mitm · December 17, 2019, 3:28pm

A variable can be set for all links. I can do that in the header of the docs.

I dont know enough about travis or even if travis can can read from other repos like that though.

mitm · December 17, 2019, 3:32pm

The variable is localized to the document. So all docs with links to wiki would still require updates, basically still at square one unless travis can do it on commits.

Edit: I can set one variable to update them all I believe. Will have to experiment some.

mitm · December 17, 2019, 7:28pm

I added a global attribute and reset all links for wiki contributors.

github.com

jMonkeyEngine/wiki/blob/9d0e4fd07d019c3d41c6b9e64b2a1a5b7e0ed774/build.gradle#L39


		//'imagesdir':'/images',
		'toc':'left',
		'icons': 'font',
		'setanchors':'true',
		'idprefix':'',
		'idseparator':'-',
		'docinfo1':'true',
		'wiki_link_edit_prefix': 'https://github.com/jMonkeyEngine/wiki/edit/master/src/docs/asciidoc',
		'wiki_link_create_prefix': 'https://github.com/jMonkeyEngine/wiki/new/master/src/docs/asciidoc',
		'orgname':'jMonkeyEngine',
		'link-javadoc': 'https://javadoc.jmonkeyengine.org/v3.3.0-beta1@'
	options header_footer: true,
		template_dirs: [file('src/templates/slim').absolutePath]
/*
	extensions {
		block_macro(name: 'iframe') {
			parent, target, attributes ->
			String content = """<iframe src="${target}"></iframe>""";
			createBlock(parent, "pass", [content], attributes, config);
		}
	}

This is set in the gradle file but can be overridden in the document headers whenever the need arises.

https://wiki.jmonkeyengine.org/wiki/wiki_header.html#link-javadoc

I guess we will just set this whenever with new engine updates.

mitm · December 17, 2019, 7:43pm

Seems some other changes were made that I was unaware of.

Like

link:{link-javadoc}/com/jme3/material/RenderState.html#setColorWrite(boolean)

had the parenthesis changed to -.

link:{link-javadoc}/com/jme3/material/RenderState.html#setColorWrite-boolean-

Anymore surprises I should be aware of?

RiccardoBlb · December 18, 2019, 8:31am

I added a global attribute and reset all links for wiki contributors.

This seems like the best solution

Seems some other changes were made that I was unaware of.

The previous javadoc was very old, it was probably generated with java7 or 6. I wasn’t aware of these changes either.