I'm trying to document VHDL base code of my company which is segmented by subdirectories containing 1 module reusable for our projects.
One module can contain a lot of VHDL files, so with a lot of modules, the documentation becomes really hard to read. I want to organize my documentation per module into a single page. Every module is independent to each other.
Do you know a solution to do this? The /addgroup command is close from I want to achieve but doesn't show the hierarchy as "Design unit Hierarchy" does.
It is not documented on doxygen.
Related
To manage your bibliography and in-text citations, which tools are best to use in Emacs? I am pretty confused about for instance helm-bibtex, org-ref, and ebib. Are these different packages for the samae thing? Thanks!
org-ref: a reference management system that integrates tightly with org-mode. I think of it like a lightweight Zotero but fully inside emacs (eg you can edit bibtex files, insert citations, search/download PDFs for references, insert bibliographies, etc). The youtube video on the Github page does a pretty good job explaining what it does and its intended workflow.
helm-bibtex: a search tool for .bib files. Execute helm-bibtex and it presents a list of whatever .bib files you configure it to search. When you 'select' something you have the option of navigating to the URL, opening the PDF, inserting the entry as a citation, inserting the BibTeX entry, etc. Also there is another command called ivy-bibtex which is confusingly part of the helm-bibtex package which does the same thing but with ivy. Furthermore, org-ref depends on helm-bibtex so consider the features of the latter to be a subset of the former.
ebib: as far as I can tell this is separate from the other two but looks like it overlaps with org-ref (or at least it has the ability to download PDFs, insert citations, follow URLs, search .bib files, etc). The main difference is that it appears the intention for ebib is to provide a nice tool for editing .bib files themselves, although it can do more than just that.
FWIW I personally use Zotero for managing my .bib files and then search/insert from them with ivy-bibtex/helm-bibtex when writing. I have ebib and org-ref half-configured but I never really needed to use them given that Zotero makes up for alot of the features that don't directly involve writing a manuscript. I also prefer to write in straight LaTeX rather than use org-mode's export functionality (just personal preferences), so this also removes the incentive for me to use org-ref since it seems geared toward writing in org-mode itself.
You can obviously do whatever you want just using Emacs packages and not rely on Zotero at all, but that should give a sense of what functionality each package provides.
I am working on a Firefox extension it is a context menu for automating bbCode, HTML, MarkDown, etc.
It is functional now, but I have a file which is the size of the rest of the code combined, an Excel spreadsheet. (Yes, I know, lame)
I use it as a database for organizing the menu IDs, arguments, internationalization, etc.
It's useful, for me at least, and I want to make it available, but it is not properly a part of the application, it should be a part of the background documentation.
Is there a way in Github/Git to separate documentary files from those that a part of execution of the code?
I've looked through Github, and I haven't found a spot (with revision control) to put this.
A lot of literature on the web teaches the difference between app/design and skin
and goes to great length to describe all of their subdirectories and how they relate
to each other. However I am struggling with another part of the Magento directory tree.
What is the difference in the purpose of the app/code/local and app/etc/modules .
While custom code goes in app/code/local is app/etc/modules where the code needs
to be declared to actually appear in the admin panel?
Thanks.
In principle your assumptions are correct.
The .xml files in app/etc/modules are used to generally manage all the modules (assigning code pools, declaring dependencies, switching them on and off).
The declarations in these .xml files of app/etc/modules is what makes modules "appear" in the admin panel under System > Configuration > Advanced (but they do not make module menus, tabs, grids or the like appear in the admin panel. That's the job of your modules configuration files).
The app/code/local folder contains local modules and their files themselves, like the controllers, observers, blocks, helpers and configuration files.
app/code/local is local code pool for magento modules. If you have a purpose to change the logic somehow, local code pool is the place where everything should be done.
app/etc/modules is a place where you can put main config file for your module, which can help the system to understand about your module.
To get better idea, visit: http://knowledge.santanu.net/developer-guide-for-magento-module-structure-and-codepool/
hey everyone, we just added a nightly action to process the entire source tree with doxygen and place the output onto development webserver.
We also already have a sharepoint structure which holds design documents for various modules/projects. Currently, the level at which we are keeping this documentation is relatively high. We discuss structures of modules and talk about the major classes, but never go down to the individual method level. I wanted to bridge that gap by having hyperlinks in the SDS word documents that would point to doxygen output.
I noticed the links look like this:
http://example.com/docs/ProjectName/d4/d98/class_c_reader.html
http://example.com/docs/ProjectName/d4/d16/class_c_stream.html
The part that sketches me out a bit is "d4", "d98" and "d16" strings in the path. If I copy these links and create the hyperlinks, does anyone know if these URLs are guaranteed be preserved in the future. As I said, entire doxygen output gets regenerated nightly.
You can disable the d4/d98 subdirectories by disabling CREATE_SUBDIRS in the doxygen configuration.
Whether the name of the HTML files will stay the same I do not know for sure but from what I have seen when using doxygen it seems so. If you want to know for sure you can always look at the doxygen source.
Probably these links will not stay permanent.
Furthermore, Doxygen has a XML representation of the generated documentation but even this interface resp. the corresponding DSD has been changed with new releases of doxygen. This is quite frustrating, as we had used the XML representation for a similar application with the assumption that the structures would be kept identical with every new release.
In order to provide nice URLs between parts of our app we split everything up into several modules which are compiled independently. For example, there is a "manager" portion and an "editor" portion. The editor launches in a new window. By doing this we can link to the editor directly:
/com.example.EditorApp?id=1
The EditorApp module just gets the value for id and loads up the document.
The problem with this is ALL of the code which is common between the two modules is duplicated in the output. This includes any static content (graphics), stylesheets, etc.
And another problem is the compile time to generate JavaScript is nearly double because we have some complex code shared between both modules which has to be processed twice.
Has anyone dealt with this? I'm considering scrapping the separate modules and merging it all back into one compile target. The only drawback is the URLs between our "apps" become something like:
/com.example.MainApp?mode=editor&id=1
Every window loads the main module, checks the value of the mode parameter, and and calls the the appropriate module init code.
I have built a few very large applications in GWT, and I find it best to split things up into modules, and move the common code into it's own area, like you've done. The reason in our case was simple, we had some parts of our application that were very different to the rest, so it made sense from a compile size point of view. Our application compiled down to 300kb for the main section, and about 25-40kb for other sections. Had we just put them all in one the user would have been left with a 600kb download, which for us was not acceptable.
It also makes more sense from a design and re-usability point of view to seperate things out as much as possible, as we have since re-used a lot of modules that we built on this project.
Compile time is not something you should generally worry about, because you can actually make it faster if you have seperate modules. We use ant to build our project, and we set it to only compile the GWT that has changed, and during development to only build for one browser, typical compile times on our project are 20 seconds, and we have a lot of code. You can see and example of this here.
One other minor thing: I assume you know that you don't have to use the default GWT paths that it generates? So instead of com.MyPackage.Package you could just put it into a folder with a nice name like 'ui' or something. Once compiled GWT doesn't care where you put it, and is not sensitive to path changes, because it all runs from the same directory.
From my experience building GWT apps, there's a few things to consider when deciding on whether you want multiple modules (with or without entry points), or all in one: download time (Javascript bundle size), compile time, navigation/url, and maintainability/re-usability.
...per download time, code splitting pretty much obviates the need to break into different modules for performance reasons.
...per compile time, even big apps are pretty quick to compile, but it might help breaking things up for huge apps.
...per navigation/url, it can be a pain to navigate from one module to another (assuming different EntryPoints), since each module has it's own client-side state...and navigation isn't seamless across modules.
...per maintainability/re-usability, it can be helpful from an organization/structure perspective to split into separate modules (even if there's only one EntryPoint).
I wrote a blog post about using GWT Modules, in case it helps.
Ok. I really get the sense there really is no "right" answer because projects vary so much. It's very much dependent on the nature of the application.
Our main build is composed of a number of in-house modules and 3rd party modules. They are all managed in seperate projects. That makes sense since they are used in different places.
But having more than one module in a single project designed to operate as one complete application seems to have overcomplicated things. The original reason for the two modules was to keep the URL simple when opening different screens in a new window. Even though had multiple build targets they all use a very large common subset of code (including a custom XML/POJO marshalling library).
About size... for us, one module was 280KB and the other was just over 300KB.
I just got finished merging everything back into one single module. The new combined module is around 380KB. So it's actually a bit less to download since most everyone would use both screens.
Also remember there is perfect caching, so that 380KB should only ever downloaded once, unless the app is changed.