Comments (9)
Clang doc could be another option: https://jessevdk.github.io/cldoc/
I like the CMS idea but how is that different from doxygen? after a, very quick, first look seems pretty similar to me.
from grid.
Yes it is quite different from Doxygen and the Clang doc you are proposing. Sphinx is just a framework to build a website, specially targeted at documenting code. But it does not generate automatically pages based on the code which I believe is the main purpose of Doxygen.
I was proposing that because a "human-made" documentation can be much more concise and to the point that a generator like Doxygen that will parse the entire code. I was really thinking it about a more dynamic alternative to a LaTeX document.
from grid.
by looking at a couple of examples I had the idea of a human created content + the actual documentation of the function/classes/... done in a somewhat automatic way from the code.
We need the second part if we want to avoid obsolescence in my view or we are still in the case of a pdf, with hyperlinks.
Happy to use Sphinx but both segments can be done with doxygen in any case. We had a tutorial part in our doxygen iroiro documentation, for example http://suchix.kek.jp/guido_cossu/documents/DoxyGen/html/Using.html
from grid.
This might be a bit of a personal taste, but I actually do not quite like the fact that Doxygen requires you to write the documentation in the code. My personal experience is that I found painful to read headers from other codes that were completely scattered due to Doxygen text within the code.
I was more inspired by something like the QDP++ PDF documentation that I found very short and efficient. But you might have more experience with Doxygen and think that we can achieve the same thing with it? For example, is it possible to write Doxygen pages without actually putting comments in the code (i.e. in Markdown/HTML or something)?
from grid.
I do understand your concern. I personally find documentation in the code quite useful but it is not mandatory for me, we could ask around for the preference in the community to have a better idea. At the end the documentation is for the users.
I used doxygen markup language to create the pages in the link I posted. Of course those are manually created but can point to the automatically generated pages from the code quite easily (essentially by name matching).
We used a single file but that can be separated in several ones
https://github.com/coppolachan/IroIro/blob/master/lib/Main/documentation_pages.h
I did not try to create a latex pdf version of this but should be fine and QDP like, I think.
Again, doxygen is not necessary but I find it better integrated to the automated documentation that can be browsed, and that saved my life when managing to understand chroma and all the templates scattered in the code (not too different from Grid in this respect).
from grid.
Personally, I think we do need a PDF or similar with human generated design philosophy.
Just a question of when, not if.
from grid.
PDF (or web pages) on the design choices and general ideas behind the structure is needed, that is sure, I think everyone agrees on that.
Let's discuss when, how and if we need a commented code that can be browsed.
from grid.
I promised carleton I would produce some form of documentation this quarter.
from grid.
Closing until someone reads the documentation I wrote...
https://github.com/paboyle/Grid/blob/develop/documentation/Grid.pdf
from grid.
Related Issues (20)
- Very low acceptance for SU(2) 1 adjoint flavour RHMC HOT 2
- NERSC and ILDG files always claim to be SU(3) HOT 2
- HMC on A100 spends large amounts of time in memory copy HOT 3
- MPI2 romio321 library fails when reading >= 2GB per rank HOT 2
- Cannot compile the gparity and adjoint versions of the CompactWilsonCloverAction
- Compilation errors and warnings build targeting Nvidia GPUs HOT 2
- GPU Benchmark_ITT segfaults with MPI and ranks > 1 HOT 9
- Create a version of Benchmark_ITT including Clover instead of Wilson
- Grid fails to build for Nc != 3
- hipcc on Crusher: function bcopy undefined (compiler does not have openmp enabled?) HOT 1
- Certain operations involving SitePropagator::scalar_object won't compile with CUDA for Nc > 3
- make install doesn't install all headers due to duplicate Config.h and Version.h HOT 3
- Using ILDG checkpointer causes a crash during write HOT 2
- Develop is broken HOT 1
- ARM NEON is broken HOT 2
- Feature request: provenance tracking
- Add hint to shm error message
- Cuda error invalid device ordinal
- Recent commit causing Grid build to fail
- The configure options --enable-setdevice and --diable-setdevice have no effect
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from grid.