Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I have a maven project that has both code and documentation (pdf files). When I create a release of my software, I'd like to package the jar file and the documentation for the user. Is there a "correct" way to do this in maven? Should I have a multiple modules - one for the code (it's a small project, so the code is a single module right now) and one for the documentation? One module for each documentation pdf? Or some other way to package it in a single project? Any help with this would be appreciated.
thanks,
Jeff
When I create a release of my software, I'd like to package the jar file and the documentation for the user. Is there a "correct" way to do this in maven?
I would use the Assembly Plugin to create a zip and/or tar.gz distribution of the project containing both the jar and the various PDFs files.
Should I have a multiple modules - one for the code (it's a small project, so the code is a single module right now) and one for the documentation? One module for each documentation pdf? Or some other way to package it in a single project?
I don't really see the need, I'd keep everything in a single module and put the PDF in src/main/doc or something like that.
Take a look at the following post: Creating Documentation With Maven, It could very well answer your question.
Related
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 3 years ago.
Improve this question
Problem statement: Every service has a separate repository. what is the best way to use a common framework across several service repositories?
We are trying to create an API test automation framework using "Karate".
Here we want to create a framework(Which can be distributed(example:jar)) such that it can be used across all of the microservice project repositories.
As the creator of Karate, I strongly recommend you don't do this. In the long term this makes all your projects depend on one common framework - and you should try to reduce the creation of "home grown" frameworks. Especially for a testing framework, you should try not to force teams to depend on an additional library which you need to maintain and version-control. Re-use can cause more harm than good especially in the context of testing, see this article at the Google Testing Blog.
That said, since Karate can read files from the classpath: you can "ship" a JAR file with common Java classes and even feature or JS files that all your projects can inherit from or "re use". In fact the karate-base.js has been designed to solve for common bootstrap logic or variables / parameters being supplied from a JAR file.
Short Answer: use normal Java techniques (Maven / Gradle) to create a re-usable JAR file. There are multiple ways to use resources (Java, *.feature, JS) from a JAR file. It is up to you how to structure your Maven (or Gradle) projects to make this happen.
EDIT: for those looking for how to create a "runnable" JAR, please see https://stackoverflow.com/a/56553194/143475
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 5 years ago.
Improve this question
the project I am working on ship a package that contains API for different languages: Java, Python, C#, and others. All these APIs shared mostly the same documentation. The documentation should be available in PDF and HTML separately on our website. The user usually download/browse the one it is interested in.
Currently we use sdocml, but we are not that satisfied and so we want to move to a more up to date tool and we are considering Sphinx.
Looking at the Sphinx documentation I cannot clearly figure out how:
1- say to generate the docs for a certain API (for instance the Java one)
2- does autodoc works for any domain?
3- is there a c# extension?
Any help is most welcome!
The best way to combine different languages in one Sphinx project is to write docs without autodoc or other means of automatic generation. For the most part they are available only for Python and even if some extension out there does allow other languages, you will be buried under different workflows before you even notice.
Salvage your docs from the code and write them in concise manner in a separate docs folder of your project or even separate repository. You could use the generic Sphinx directories like class or method with no attachment to the code and for virtually any major programming language. I for myself did a project like that, where I needed to combine C, C++ and Python code in one API and it was done manually.
If you create this kind of detached project, the maintenance should be much of an issue. It's not much harder, than autodoc workflow. What for PDF and HTML - any Sphinx project allows that. See their docs for details on different builders like latexpdf or html.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I'd like to write an architecture document for a little ruby project I'm working on, and being an architecture document it'll benefit from a few box and stick diagrams.
What's the done thing on open source projects for this situation? Should I be practicing my ASCII art, or should I include PDFs or something in my doc folder?
Note that this is a stand-alone document, not API documentation generated from the code.
Check out umlet-github, a Google Chrome extension that allows you to create diagrams in UMLet, store them as UXF files in your repository and view them in your browser within the GitHub interface.
I would say use Gliffy, where you can export diagrams to .JPG or .PDF and attach them to your README.md file.
You can also get a sharable link and include it in there. Very handy.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
Неllо. I develop system that works with stock exchange(system, below). And there is a lot of information my program need to interact with this system. This system has formal declared interface, but different details beside this declaration and requirements to my system is often changed. So how can I organize available information about this system and requirements to my program that it could be both easy to understand and easy to change.
Your first and foremost goal is to create documentation for the relevant APIs your program exposes and then add documentation for the configuration files, maybe even set up a validator for configuration that.
Automatically generated content from code annotations (depending on your solution, it might be .NET's XML docs or PHPdoc, etc.) is the first step – this will help you document classes and interfaces as you work on the code. The next step is documenting non-code assets. If you have XML configuration, you can write schemas to validate against, for example.
After that comes integration documentation – steps that need to be taken on the production server and/or workstations to install, upgrade and maintain the application, including support scripts.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I've recently moved my project from sourceforge to Google code. I'm intrigued by the Google code wiki that is integrated with svn, but I'm not sure of the best way to use it to provide project documentation.
For my project, documentation could appear in three places: (1) on the wiki, (2) in the desktop application I'm developing (using wxPython), and (3) on the project website (which is http://www.openstv.org and is Drupal based).
I like the idea of using the Google code wiki as the primary source of the documentation, and then automatically incorporating this documentation in both the desktop application and on the project website .
Does anyone have any suggestions for doing this?
The Wiki files live in Subversion -- just svn checkout http://yourproject.googlecode.com/svn/wiki yourwiki and you get a yourwiki SVN repository that's easy to keep updated (just svn up in it once in a while, e.g. in a crontab).
The format of the Wiki files is a Google variant of ReSTructured Text so you could write scripts to convert it to plain ReST and from there to whatever other formats you prefer for your other uses -- or, write ReST on your system, convert it to whatever you like (including perhaps Google's wiki format;-), and upload that...