erez-o / docsforge Goto Github PK

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.

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, relatesand relatesalso. I haven't tried them, but I guess they cause the same problem with DocsForge.

Switch project configuration from JSON to Yaml to Increase readability

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:

1. The user will decide which files or folders he wishes to scan and upload. By design, It won't be automatically created from the input of autodocSettings to allow flexibility.
   a. Any inner files or folders would be uploaded recursively
   b . In the future add additional filters like exclude, exclude_patterns, include_file_extensions, exclude_file_extensions...
2. Currently source browsing is done in github - the 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.
3. Source browsing is optional. If a maintainer chooses to send source browsing links to github instead because he thinks it's more suited for his users, he should be allowed to.

In https://c4core.docsforge.com/ the public api section disappears when navigating to any inner api

Support rendering markdown as close to github's rendering

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?

Need to convert relative links and image links to raw.githubusercontent.com automatically

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.

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).

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().

add when pressing enter in project screen search.

Allow sorting by type, alphabetically, or by order of appearance in the code.

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?)

Some table cells are too high and it hurts the consistency of the api summary pages.

Add js show more/less to fix.

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,

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:

1. The initial "A" appears as code

2. 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 (!).

Discovered an issue where the the output if a code comment contained /par with a title (see here) was suboptimal.

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 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:

• https://breath.docsforge.com/master/api/breath/to_lowercase/ (paragraph "Naming Rationale")
  and
• https://breath.docsforge.com/master/api/#BREATH_ASSERT (paragraph "Rationale"; please, click "Show More" if needed)

Add custom CSS & JS per project.

Regarding JS I'm on the fence because users can add harmful scripts.

A flag that allows to first split the pubic api sidebar according to source files (for example foo_file.h, foo2_file.h, etc)

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

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).

Sidebar isn't always scrolling correctly on ipads

Hi,

it seems that DocsForge correctly renders \pre and \post documentation with separate paragraphs but gets their titles wrong; see the attached image.

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).

until it, i'll use jsdoc2md or typedoc

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.

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

Noticed in docsforge version 3.4.19

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 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!

Print to build log

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

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.)

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.

Allow each define to be displayed on a separate page, similar to how function pages are presented

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".

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.

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?

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.

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.

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/

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?