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.

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

Sphinx2 #173

Closed
wants to merge 16 commits into from

Conversation

Projects
None yet
3 participants
@Alberth289346
Copy link

commented Jul 30, 2014

Except for the last 2 commits, these are all changes / improvements to the ags.tex file. I cannot build the output from it, since I cannot compile tex2rtf at my system, so I my have broken the .tex file. Please verify.

Commit 55602ec adds the same manual, but in Sphinx format. This is a text format, with markup in plain ascii. The tool can produce a multitude of output format, including html and windows help files. It is an industral-strength tool, docs.python.org is generated with it, containing all documentation for every Python version. The .RST files are sources, other things are build files. I added a short README.txt as well explaining how to build HTML and Windows HTML Help files.

Commit cf90273 adds a Python 3 conversion script, and a patch file for the last changes that the conversion script missed. You don't actually need these files, but they may be useful perhaps.

@ivan-mogilko

This comment has been minimized.

Copy link
Member

commented Jul 3, 2016

Having other priorities, I was not able to thoroughly check all the changes proposed here at a time, and this pull request was "freezed" undefinitely. I guess it makes little sense to discuss it now..., but the reasons I did not want to merge it as it is in the past were that it changed too much at a time (beautification of ags.tex is one thing, but adding Sphynx files is another), and I doubted I would be able to review the results of those changes on my own.

Now when I have little more time, I think I could try to apply some of these patches at least to see how they improve the looks of existing manual.

@Alberth289346

This comment has been minimized.

Copy link
Author

commented Jul 3, 2016

Thanks for the update.

Yeah, I stopped hoping anything would be done with it after a few years. Apparently the step was too big. I don't know how to convert to a different documentation system in small steps though.

If you want to discuss something about the patches, I might be able to help you, if I still remember it :)
I won't do the conversion again, though.

Maybe sphinx is not the right answer nowadays. wiki markup languages have become more popular, so you might want to consider switching to markdown or asciidoc instead.

@ivan-mogilko

This comment has been minimized.

Copy link
Member

commented Jul 3, 2016

It was not so much because the changes were big, but rather that it was lower priority for me, personally, and I was kept distracted by working on the program code all time.

I think @sonneveld is suggesting markdown; but regardless several of your commits here propose cleanup and improving style consistency that could be useful before any switching is done. I would need to test these carefully though, because final output target is still Windows CHM, and it may have unexpected results sometimes.

@sonneveld

This comment has been minimized.

Copy link
Member

commented Jul 3, 2016

Perhaps we could only merge in @Alberth289346 's conversion and build scripts for now. Our teamcity user manual build task could build the manual from tex as per usual but also run the rST conversion/build to test.
The primary source would be .tex until we're happy with the conversion and then migrate to only using rST.

@ivan-mogilko

This comment has been minimized.

Copy link
Member

commented Jul 3, 2016

I do not really see a reason to put conversion script to the main repository, because it is supposed to be used only once, after that it becomes completely redundant.

@sonneveld

This comment has been minimized.

Copy link
Member

commented Jul 3, 2016

But that's my point, we could run it for every build until we're happy with the conversion.

@ivan-mogilko

This comment has been minimized.

Copy link
Member

commented Jul 3, 2016

Cannot the script be placed somewhere else instead and still be usable by server?

BTW, do I understand correct that this is basically LaTeX to rST conversion; does it have anything specific to AGS?
Thing is that I searched for converter before, and saw this: http://pandoc.org/

@sonneveld

This comment has been minimized.

Copy link
Member

commented Jul 3, 2016

It can be placed on the build server but it makes it hard for other people to test it locally and I anticipate that we'd probably want to adjust the script as we continue to add content to primary .tex source.

I haven't looked at pandoc. I wonder what the output is like for converted documents. We'd still need to keep track of the settings used for conversion though and it would be easier to keep track in the repo.

@ivan-mogilko

This comment has been minimized.

Copy link
Member

commented Jul 4, 2016

OK.
But I guess it is better to first try out available converters and compare what they produce.

@ivan-mogilko

This comment has been minimized.

Copy link
Member

commented Jul 31, 2018

The manual is now remade into MD source and available in the separate repository: https://github.com/adventuregamestudio/ags-manual

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.