crisluengo commented 5 years ago

I've tweaked your code here and there to make it fit my documentation and my style. Here is a subset that I think might be useful to others as well.

I suggest you cherry-pick the commits that you like, if any. I understand some of these things might go against your style/tastes/ideals/whatever. It's all good. I appreciate all the effort you put into this and am very grateful that you make it available. :)

I did not bother with tests, since I didn't know if you wanted to keep any of these changes. Sorry.

I think the commit messages are fairly clear. Some motivation:

Regarding table layout: I'm following classical layout standards, see for example the LaTeX booktabs package -- the introduction at that link is a very nice summary of table layout practices.
Regarding \m_div and tables: not sure if I was doing something wrong here, but I got errors when trying to reduce the font size of a table using \m_div (or @m_div, not sure why I always use the backslash form). This fixed it. I don't know if it breaks something else...
~~Regarding "none" syntax highlighting language: my documentation had a few code blocks with "none", maybe Pygments has a different name to use there, I don't know.~~
Regarding duplication of detailed member description: I was getting detailed descriptions for all functions in the base namespace of my library (there's a lot of them!), and again in the group pages. The base namespace page, in the list with short descriptions, linked to the group pages, not the detailed descriptions lower down on the same page. Because different functions here have different include files, the detailed descriptions were forced on. This fix probably breaks something else!

crisluengo commented 5 years ago

Ignore that last commit. It's not a correct fix for the issue I was seeing.

I'm trying to fix this properly, but it's hard to do. I'll crack it eventually. :)

mosra commented 5 years ago

Hi, thanks a lot! :heart_eyes:

I'll be definitely cherry-picking some things from there, however it might take me some time -- still way too many things to do.

Regarding table layout

Interesting. I will definitely read through that -- all the layout & typography I did for m.css was based on my past personal experience and my own idea of what "felt right", never attended a typography school or anything so I'll gladly learn how to do things better :)

Regarding \m_div and tables

The \m_div command has a very limited use since Doxygen is absolutely crappy when it comes to nested block elements -- if you place it in a separate paragraph, then it will get wrapped as <p><div class="..."></p> and that is absolutely awful. I tried to come up with some generally acceptable solution for this, but so far I only have a bag of workarounds of varying ugliness. For your particular case, I think you could do it via \m_class instead like below (adapt to your docblock style, of course) -- I'm using the following quite often to make tables fullwidth and so:

/**

\m_class{m-text m-small}

A table | Some other column
------- | ---------------
yay     | this is smaller, hopefully

*/

maybe Pygments has a different name to use there

I think \code{.txt} is the thing you're looking for: http://pygments.org/docs/lexers/#special-lexers

Regarding duplication of detailed member description

Yes, I anticipated this to become a problem :D Some ideas:

Is the include information for each member desired to be shown? If not, I could add a command to disable that on a per-member basis (or, hopefully, reuse some existing Doxygen command, there's enough of the \m_foo ones already)
Or, in case the include information for each member is wrong (or you'd want to show a different one), a better variant of that command could be to override the include info, something like \m_includefile{#include <ProperHeader.h>} -- looking forward to how many new exciting Doxygen parsing bugs that will uncover, tho :laughing:
There's also a way to disable showing the include information altogether (useful if your lib is a single header, for example) using SHOW_INCLUDE_FILES, maybe that's what you're looking for?

crisluengo commented 5 years ago

Regarding \m_div and tables

Yes, you're right. It is possible to apply classes to tables using \m_class.

That commit is totally mislabeled. I blame my memory. :/

It actually allows bulleted lists (also ordered lists) inside the simpleselect boxes. I needed to create a box for literature lists, made a Doxygen command \literature...\endliterature for that, and somehow end up with <para><simplesect kind="literature"><itemizedlist> in the XML. So the list's parent is simpleselect, which doxygen.py didn't expect.

This is probably very localized and/or caused by me doing things wrong.

I think \code{.txt} is the thing you're looking

Ah! Makes sense. Thank you!

Regarding duplication of detailed member description

Actually it makes sense to show the include file name, this is why I'm trying to find a different solution than not showing the detailed information at all.

The problem is this:

I have a namespace with hundreds of free functions. I divide these into modules (groups) to make them easier to discover in the documentation. Free functions for each module are in a separate header file. The output HTML has this structure:

namespace.html
 - function1 -> links to group1.html#function1
 - function2 -> links to group1.html#function2
 - function3 -> links to group2.html#function3
Detailed description function1
Detailed description function2
Detailed description function3

group1.html
 - function1 -> links to #function1
 - function2 -> links to #function2
Detailed description function1 (#function1)
Detailed description function2 (#function2)

group2.html
 - function3 -> links #function3
Detailed description function3 (#function3)

In namespace.html there is the detailed description for all (hundreds) of functions, but nothing links to these descriptions. The list with short descriptions at the top of the file links to the detailed descriptions on the group pages. I'm trying to turn off the detailed description only if the URL for the function is not the current URL. I've gotten this to work in many cases, but not everywhere. Not sure yet why.

When I figure this out I'll submit a proper pull request with tests and so forth. :)

mosra commented 5 years ago

So the list's parent is simpleselect, which doxygen.py didn't expect.

This is probably very localized and/or caused by me doing things wrong.

I see. No, you're not doing things wrong, this is a valid use case -- the assertions are a bit too tight sometimes. A test for this would go to contents_block/input.dox, if you want to do that :)

In namespace.html there is the detailed description for all (hundreds) of functions, but nothing links to these descriptions.

Seems suspicious. Is it possible for you to create a minimal repro case and paste it here? I might have an idea where the problem could be (or what code could be responsible), but don't have time to dig through thousands of functions right now :sweat_smile:

crisluengo commented 5 years ago

I've removed those last three commits, since those were all my misunderstandings.

I have found the issue with the duplicate detailed descriptions, and will submit a separate pull request for that with proper tests.

mosra commented 5 years ago

Sorry for not being able to look into the PRs yet, I'll jump on that next week once I'm a bit more free than now.

Just wanted to say this, tho -- congrats on shipping https://diplib.github.io/diplib-docs/, the style is very pretty :)

crisluengo commented 5 years ago

Thanks! And thank you again for putting these tools out. They're absolutely awesome!

No hurries with any of these PRs. I hope some of that is useful to others. And sorry for not getting perfectly clean checks... I tried.

mosra commented 5 years ago

Merged the recursive variables commit as 4f5b7982d30645e61fba82219306d7895108e2d2 and the line height customizability as d9daee68aebfc5402c086b3274c19e4fb18614e9 (though I defined it as normal in the style to avoid an unwanted change).

What's left is the tables (I'm a bit unsure about the changes, need to inspect visually what the difference is, especially regarding the now-gone border) and the CSS flex property to fix the page height (not using CSS flex grid yet, see also #31). Will look into these again later, hopefully.

codecov[bot] commented 5 years ago

Codecov Report

Merging #101 into master will increase coverage by 2.32%. The diff coverage is n/a.

@@           Coverage Diff            @@
##           master   #101      +/-   ##
========================================
+ Coverage   97.67%   100%   +2.32%     
========================================
  Files          22      1      -21     
  Lines        4737    379    -4358     
  Branches       40     40              
========================================
- Hits         4627    379    -4248     
+ Misses        110      0     -110

Impacted Files	Coverage Δ
plugins/m/abbr.py
plugins/m/alias.py
plugins/m/plots.py
plugins/m/link.py
plugins/m/filesize.py
plugins/m/components.py
plugins/m/metadata.py
plugins/ansilexer.py
documentation/doxygen.py
plugins/m/gl.py
... and 11 more

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 1dc7c2a...ecb730d. Read the comment docs.

mosra commented 5 years ago

Oh dang, now the remaining commits are gone :sweat_smile:

crisluengo commented 5 years ago

I did what? Shoot! I didn’t realize I had send a PR from the master branch... Who does things like that? :)

I’ll try to get this stuff back tonight.

Sorry!

mosra commented 5 years ago

Found them: https://github.com/mosra/m.css/commit/ff8c109ea73922df1e6bf7ec044e33362f802432 and https://github.com/mosra/m.css/commit/ecb730ddd0b9210eec84f10a855978260ec79625 ... but I assume those will last only until the next git gc round at GitHub :)

If you make a branch out of those two (and link it here for reference), that should be enough to keep them from getting lost.

crisluengo commented 5 years ago

Footer at bottom of the page: https://github.com/crisluengo/m.css/tree/footer_at_bottom Improved table layout: https://github.com/crisluengo/m.css/tree/improved_table_layout

mosra / m.css

Assorted changes and fixes #101

Codecov Report