erez-o / docsforge Goto Github PK
View Code? Open in Web Editor NEWModern C/C++ documentation generator for open source projects.
Home Page: https://docsforge.com/
Modern C/C++ documentation generator for open source projects.
Home Page: https://docsforge.com/
Hi again,
this is basically the same screenshot I attached to the previous issue report:
It seems (see the documentation of max()
, min()
and next()
) that DocsForge picks up the \return
paragraph here, including the command itself without the leading backslash. Doxygen emits the following, instead:
I'm not sure that I'm also not doing anything wrong here. If so, please tell me.
Cheers!
For debugging purposes, seeing doxygen's html output can be quite useful
.
This is especially true when playing with doxygen's preprocessor commands.
Instead of requiring the users to install doxygen on their local pc, it's better to allow displaying its html in docsforge.
This debugging
flag will be disabled by default, since it takes extra time for project docs to built.
Support rendering markdown as close to github's rendering
Hi,
even in its brief description, I often refer to the parameters of a function. For instance, I might have:
//! Calculates the product of \c a and the square of \c x.
int square( int a, int x ) ;
For such a function, DocsForge would display something like:
F | square | Calculates the product of a
and the square of x
.
without the function parameters (or the return type), so the documentation would look like something extracted at random without a context :-) Could you please show the parameter list and the return type? This is especially important when functions are overloaded. (I have a vague memory that we quickly touched this topic, but I can't remember the details.)
Hi,
Doxygen allows the user to prevent a word from being autolinked by putting a %
in front of the word. I think (though I've not verified that), given the regular expressions listed in the documentation and the fact that DocsForge acts (AFAIU) after Doxygen has produced its output, that DocsForge would link such a word anyway. That would be against the user will, of course.
I'm not sure how to fix this, as I guess the % sign is simply absent in the Doxygen output.
Note that all of the above is speculative and might just be my imagination of how things would go. But I didn't want to lose the opportunity to report the issue, in case it's really an issue.
Users will be able to supply their own html template, and fully customize how their documentation looks.
The only suggested fields the user should always keep are {{sidebar}}
the actual {{page_content }}
, and the {{choose_version}}
button.
But any other layout, buttons, css, js can be changed as the user sees fit.
Hi,
it would be nice, for keyboard-centric people like me :-), to add an accesskey
attribute for the DocsForge search box. I'd suggest "s", as it is the initial of "search" and also what Doxygen uses in its generated HTML pages. What do you think?
Hi again,
throughout my documentation (breath.docsforge.com) some paragraph titles are duplicated. It seems that this happens with all paragraphs created with a \par command (but I haven't done an exhaustive verification). Examples are:
Hi,
this is not a feature request, just an idea for you to consider: what if you let the reader choose their preferred documentation theme? The documentation author would set a default, but the reader could override it.
Add an option to add code source browsing.
Currently source files are not uploaded to docsforge, and if you wish to see the source code you're sent to github.
Source browsing in docsforge can be more helpful than in github because the files will have links to the docs of each api.
Requirements:
autodocSettings
to allow flexibility.exclude
, exclude_patterns
, include_file_extensions
, exclude_file_extensions
...source
section of api pages links to lines in the git repository (for example Lines 35-58 in dir/file.cpp.
will send you to github). Change so that if the source file exists in docsforge, send it to it instead.Need to convert relative links and image links to raw.githubusercontent.com automatically
Hi,
this is a screenshot of how the documentation of one of my classes appears:
As you can see, it seems that DocsForge tries to stop at the first sentence in the documentation, but sometimes it includes the final period, sometimes it doesn't.
Furthermore, there's a problem with the expression "i.e." (and, I guess, any other involving a dot, like "e.g."), as you may notice in the documentation of the first overload of set_name()
. Which is weird behavior, because the letter "e" in "i.e." is included, even though it occurs after the dot (but the issue, of course, is that the dots in "i.e." should not be considered the end of the sentence).
From discord:
Css variables are supported in most browsers.
Using them gives users an easy way to customize their themes.
Downside is this will drop support for IE11, but Microsoft ended support for IE, so it's not a heavy downside.
In https://c4core.docsforge.com/ the public api section disappears when navigating to any inner api
A flag that allows to first split the pubic api sidebar according to source files (for example foo_file.h, foo2_file.h, etc)
Option to exclude (or include only) files from being displayed, but still gather implementation data.
Currently only exclude (or include only) is done for specific api pages like my_namespace::my_class
For example, your source files are split around multiple files, but you only want to display the public api that is located at a specific /somedir/my_file.h
. To gather all implementation data, you would still need INPUT=src include
Some table cells are too high and it hurts the consistency of the api summary pages.
Add js show more/less to fix.
In https://rapidyaml.docsforge.com/master/api/#variables we can see some variables. They do not come from the source code, but from some samples in the main README.
How can I avoid these?
Hi Erez,
just noticed that the link "edit your profile settings", in Home / Versions, is broken. I'm not sure what the correct URL is, but it currently points to https://project_name.docsforge.com/profile/edit, while the corresponding link from the profile page (which works for me) goes to https://docsforge.com/profile/edit/.
Cheers.
Hi,
in a couple of places in my library (breath.docsforge.com), some normal documentation is rendered as code. See e.g.: class crc. Does this have to do with Markdown support? (I have it disabled in my doxygen.cfg, but I guess DocsForge doesn't have a corresponding option?)
Hi,
it seems that a sentence like this:
At the time of this writing---October 30, 2020---I'm reporting an issue here.
is rendered as:
At the time of this writingOctober 30, 2020I'm reporting an issue here.
by DocsForge, eating up each instance of "---". The issue doesn't appear to be with Doxygen (I tried with both settings for the MARKDOWN_SUPPORT
option, just in case). An example in my documentation is here (you can search for "at the time of this writing").
P.S.: perhaps it would be better to link to a specific revision on GitHub in our issue reports? Because, considering e.g. the link to the DocsForge documentation above, nobody could see the problem if they followed the link two years from now, when the issue will have been fixed.
Hi,
the following markup:
//! \throw
//! A \c std::invalid_argument if any of the characters in \c s
//! is not a decimal digit (i.e. one of \c 0123456789).
is being rendered as follows in my documentation:
That has two oddities:
The initial "A" appears as code
An extra hyphen appears between the "A" and the rest
I suspect the glitches are due to Doxygen, though, because this is Doxygen's output, instead:
There, although there's no extra hyphen, the "A" is rendered as a parameter name (!).
Print to build log
Discovered an issue where the the output if a code comment contained /par
with a title (see here) was suboptimal.
Add custom CSS & JS per project.
Regarding JS I'm on the fence because users can add harmful scripts.
Hi Erez,
I'm here to bother you again. Would it be possible to add support for Doxygen's EXTRACT_PRIV_VIRTUAL
tag?
Speaking of this, I think that, with time, everyone will end up asking you to add support for their own "favorite" Doxygen tag. The more successful DocsForge will be, the higher the likelihood that someone will request support for some unsupported tag that they were using with Doxygen but can't use with DocsForge. So, I think a convenient way to handle the issue would be to add a general syntax to pass an option down to Doxygen directly. Something like doxygen: MY_TAGS
or similar.
Hi,
I've noticed that, in class member function lists, DocsForge uses a single entry for all the constructors of the class. E.g.:
In this case, the documented class has both a default constructor and a deleted copy constructor, but DocsForge lists one constructor, and "reuses" the documentation of the deleted copy constructor for everything. This is instead the Doxygen output with my configuration:
Note, too, that the term "method" is usually frowned upon in C++ (whether with reason or not). The "correct" term is "member function".
Allow each define
to be displayed on a separate page, similar to how function pages are presented
Allow sorting by type, alphabetically, or by order of appearance in the code.
Noticed in docsforge version 3.4.19
Each project will have multiple "alt" yaml configuration files in addition to the default one.
Users will be able to experiment with different configurations and assign a different default configuration to each version of their project.
add when pressing enter in project screen search.
Switch project configuration from JSON to Yaml to Increase readability
Hi,
I noticed that if you try to browse the documentation while a new version is being built, a nice warning appears (as in the screenshot below):
It seems that the message gets stuck, though, and stays there even when the build is finished (in the case of the screenshot, it always showed "Stage 2/6", with no advancement).
Hi,
in my library's documentation, #include
directives for files that belong to the library are all shown in the <>
form, although I always use ""
in the code.
Doxygen version 1.8.18 (a1b07ad0e92e4526c9ba1711d39f06b58c2a7459) seems to show the expected form, instead. Note that I don't have FORCE_LOCAL_INCLUDES
enabled. Why does DocsForge differ, in this regard?
Hello,
I wish to use Algolia as a search provider for my website https://anyfig.docsforge.com/. It's responsive, powerful, and free for open source projects https://www.algolia.com/for-open-source/.
It seems to me that with the current search function, you can't find any text on the website as it is limited to headings and pages (could be wrong here). Algolia is better in that respect since you can search and find specific words. To see the search in action, you can test it on my previous website https://anyfig.now.sh/
I was hoping that it could be an opt-in via the configuration file
until it, i'll use jsdoc2md
or typedoc
From discord:
Instead of having a single section "Public API" for the API documentation, would it be possible to have multiple, user defined sections?
That way I could create one of the public API, one for modules (perhaps even include modules from other repos), and one section for internals
Solution: Extend the yaml configuration file:
sidebar:
Documentation:
- Readme: README.md
- Quickstart: docs/Quickstart.md
- Manual: Manual.md
Public API:
- autodocSettings1
- autodocSettings2
autodocSettings:
C API:
baseUrl: api-c
language: c
...
C++ API:
baseUrl: api-cpp
language: cpp
...
Or another example:
sidebar:
Documentation:
- Readme: README.md
- Quickstart: docs/Quickstart.md
- Manual: Manual.md
Public API:
- General API:
- autodocSettings1
- autodocSettings2
- Modules API:
- autodocSettings3
- autodocSettings4
autodocSettings:
C API:
baseUrl: api-c
language: c
...
C++ API:
baseUrl: api-cpp
language: cpp
...
Module1 API:
baseUrl: api-c
language: c
...
Module2 API:
baseUrl: api-cpp
language: cpp
...
Or another example:
sidebar:
Documentation:
- Readme: README.md
- Quickstart: docs/Quickstart.md
- Manual: Manual.md
General API:
- autodocSettings1
- autodocSettings2
Modules API:
- autodocSettings3
- autodocSettings4
Hi Erez,
it seems that DocsForge shows functions marked with Doxygen's \relatedalso
as if they were members of the related class. Here's an example:
This is the HTML output from Doxygen, instead:
Note that Doxygen has other three similar commands: related
, relates
and relatesalso
. I haven't tried them, but I guess they cause the same problem with DocsForge.
Hi,
any idea why I'm not getting the documentation of the stream inserters of class roman
and class uuid
, in DocsForge? I can find them in the Doxygen HTML output, either going to the documentation of the corresponding classes, or typing "operator<<" in the search box. In all, I can find 6 stream inserters in the Doxygen HTML output and 4 in DocsForge.
Thanks.
In this file I use some macros to hide SFINAE ugliness. This then has a big impact in the generated documentation; for example, it says the code provides memcpy().
Hi,
in several places, the DocsForge user interface uses the term "latest" to refer to what is AFAIU the "main" documentation set. This is IMHO misleading because e.g. the documentation for the master branch (marked as "latest" by default) may, in fact, be older than that of a given branch (not only because e.g. the branch docs were generated later on DocsForge, but also because the branch can really be ahead of master by some commits). So, I'd suggest using one of the terms "main", "primary" or "principal", in this case (I'm not able to pick up what the best one is, because I'm not a native speaker and I might actually miss the exact concept you had in mind).
I just came across docsforge and the output looks super cool! I was wondering if you had any thoughts or tips about how a project with an existing readthedocs / sphinx setup might be able to get the benefits of docsforge?
An example project would be the Verilog to Routing project who's documentation can be found at https://docs.verilogtorouting.org/en/latest/ and already uses Sphinx + Breathe for some API documentation at places like https://docs.verilogtorouting.org/en/latest/api/vpr/contexts/#classes
Another example would be the Project X-Ray documentation at https://symbiflow.readthedocs.io/projects/prjxray/en/latest/
Sidebar isn't always scrolling correctly on ipads
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.