Many people document applications in the source files themselves, e.g. https://github.com/docopt/docopt.cpp . In the spirit of DRY (don't repeat yourself), I would like source documentation to appear in my README.md on GitHub (auto-generated from the source.) I see many user-community questions about including README.md in output documentation, but nothing about going the other way, src documentation -> README.md. doxygen seems like the tool that should own this space, but has no output formatters for markdown files.
Does it make sense to anybody else to create an output formatter for markdown?
Apparently it does make sense, and has been proposed before, as well as some bolt-on solutions developed: https://github.com/doxygen/doxygen/issues/6760
Related
I have two assembly files on github that should have the same syntax highlighting, but they do not as shown in the images below. The first image is wrong, comments are not grayed out, and the second image is right. Any ideas how to fix the first image?
They are probably being detected as different types of files. GitHub uses the Linguist library for this, but it's not perfect. In addition, assembly files are specifically very hard to detect because different assemblers have different register names, syntaxes, and comment forms.
You can specify an override in your .gitattributes file as specified in the Linguist documentation to force your file to be detected properly.
I'm about to submit this project but I want to make sure the Github page looks good before I do. For some reason, not all the languages are showing up and I don't know why. I've tried to find ways to edit this under settings but I've yet to find anything.
As you see in the images below, on the homepage it says the Repo is 100% Jupyter notebooks, but if you click on "languages" you'll see that there are python and csv files as well that seem to be unaccounted for.
If anyone knows how I can change this please let me know. It's not very important but I think it'd look much nicer if the breakdown of languages was more accurate. Thank you!
GitHub uses Linguist to figure out which languages are part of your project. It has a languages.yml file to defined the multitude of languages to look for. Some are markup languages (like jupyter notebook), some programming languages, etc.
That percentage you see is calculated based on the bytes of code for each language. The more you have of one type, the higher the percentage.
Note, however, that this library excludes all files that it determines to be binary data, vendor code, generated code, documentation, or defined as data (in your case csv) or prose (think markdown), whilst taking into account any overrides.
IF your python code is small enough, even in 2 files, it won't get show up. Just write more python if you want it to show up.
The second screenshot provided is when you click on the languages and it's purpose is exactly what you are looking for - to give better details on the current project and what it comprises of in detail. This language bar is just an overview. It need not be 100% accurate.
FIY - It also matters which is your main branch, since it takes that into account.
Conclusion - don't worry about it. Whoever needs to see it, will see what your project has in terms of contents.
github supports several markup languages, one of which is Emacs org mode docs.
But it always look ugly with the default CSS file(much better than
the default one in built-in org mode, though.
Also it seems that the
source code block does not have syntax highlight either.
So is it possible to make it more beautiful with some minor changes in org files? Or can you give me some advice or good practice?
Github uses org-ruby to convert org-mode to html. It appears that recent versions of org-ruby support both lower case org-mode keywords and syntax highlighting in the source code blocks (among other nice things). Until it is upgraded in the official Github, it looks like the only options are either to use upper case BEGIN_SRC/END_SRC or export your org files to html/md in emacs with any options/css/etc you like and post the resulting files on Github.
Githubs Org-Mode support is upgraded but #+TITLE: is unsupported, like links that are mostly bugged. So it works mostly.
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.
I have never used Git before. I am supposed to use it to take notes on a book, but i haven't a clue how to get started. Do I create a .text file? The only things I have found are instructions on how to keep track of projects, but nothing about the kinds of projects I might use. I just want to make a word document that can be read, altered, and printed with ease. Can anyone help me out?
To take advantage in using git for storing documentation you should use non binary formats like:
html
latex
pure text
markdown
There are many text formats that can be used for this.