if you are developing and documenting a library.. do you document every single function / data structure from every source file, or just the public ones that appear on the public header??
im leaning to the second option, is this ok?
The answer to your question depends on who is going to read the documentation. If the documentation is going to users of your API, it is probably better that you only provided them with documentation for the public interface. As this way they will not be overwhelmed by details that are not relevant to them.
On the other hand if your documentation is to be read by people maintaining the library, it should include documentation on both the public and private code.
Right now I am using a slightly different approach to arne. I have a script which copies the header files needed for the public interface to a separate directory for packaging up. This is necessary anyway for producing releases. The script also copies the Doxyfile configuration to that directory and then runs doxygen on the reduced set of files. That way I have one doxygen configuration file that I use to produce both public and private documentation.
That depends on whether you ever want to change anything in that library, say, five years from now. In that case, having documentation can come in handy. However, you should somehow separate your "private" documentation from the documentation you provide to users. This can be done by using two separate doxygen configuration files with different INPUTs.
Related
I have a SQLite FTS5 virtual table and am trying to highlight text in my prefix query results. I am aware of the highlight() and snippet() auxiliary functions, however they don't seem to support exactly what I am trying to do. If my data looks like:
fts.my_data
-----------
John
Mike
Bill
Jane
and I want to query using a prefix match such as
select * from fts where fts match 'j*';
The highlight and snippet functions (assuming <b>...</b> tags) will return
<b>John</b>
<b>Jane</b>
But I only want to highlight the exact part of the prefix that was matched, before the wildcard:
<b>J</b>ohn
<b>J</b>ane
There does not seem to be any way to do this using the existing FTS5 auxiliary functions. I realize FTS5 offers an API so that you can create your own auxiliary functions. I might also be able to implement the solution in application code (I am using Swift), although I suspect this problem has the potential for a lot of issues trying to implement in application code (for example, how to handle stemming). Does anyone know if what I am trying to do is actually possible using the existing highlight and/or snippet functions before I go to the trouble of implementing my own solution? If so, could you explain how?
Also, I have observed several other existing apps (Contacts+ for example) offer this capability so I know it is possible somehow, and am also wondering how they do it if anyone knows how.
For anyone else looking for a resolution to this issue, I was able to figure out how to solve this issue.
The trigram tokenizer was added as one of the built-in tokenizers in SQLite 3.34.0 (released December 1, 2020).
In my case, I was deploying to iOS, which at this current time, only has SQLite 3.32 bundled with it by default, as confirmed by this wiki page. So I was able to download the SQLite source code and add it as a project to my XCode workspace as a "Static Library" and reference the resulting .a static library file from within my app's project. I also had to set the appropriate C Flags in the XCode compiler options for the SQLite project to get everything to work correctly. But I am now able to distribute my own supplied version of SQLite (3.34.1), compiled with my specific options, with FTS5 and the trigram tokenizer.
I’m building a super simple website with 5 pages and I want a CMS that allows me to change the text and the pictures in a couple of them.
In the past I used wordpress, but it has way too many features that i don’t need in this case.
I’ve been trying to learn gatsby.js so I would like to build it on that, but trying to see how to source from Netlify-CMS I started facing an overwhelming amount of information which I'm not sure I need.
Any tips?
Thanks!
M
Netlify has a built in CMS, and it's compatible with Gatsby! You can find examples online. It should be good for smaller sites, but for larger projects, I really like Prismic.io. Contentful is another popular one, but it's a bit pricier than prismic.
Edit: reread your comment about sourcing from Netlify. Netlify is not a "source" plug in in Gatsby. You use a local file +markdown source, and do the configuration for netlify, which adds an admin interface at an endpoint. You configure your data models in the interface, create login, etc. Then, when you submit changes, it modifies files in your connected git repo, so the local file + remark will make the data available in the graphql queries.
In the end I used Forestry.io, a good simple solution that did exactly what I needed in combination with Jekyll.
I would like to use ReadTheDocs to host my Sphinx documentation. The project is hosted on github. I can connect to it just fine.
The particularity that I have is that the project contains 2 Sphinx documents (e.g. a programmer's manual and a user's manual). ReadTheDocs appears to be detecting both (there are two conf.py) and building both. However when it comes to displaying them, it displays the html for only one of them, as far as I can make it, the first one alphabetically.
So my questions are:
If both have been built, how do you get to see the other one?
Is there a way to use "subprojects" to specify the path to each conf.py and hence have clear URL to each document/manual? That would be the ideal solution.
Read the Docs does not support building two different sets of documentation from the same repository and same Read the Docs project. However, you could use sphinx-multiproject extension to achieve this.
You will need to define this extension in your requirements (see https://docs.readthedocs.io/en/stable/guides/specifying-dependencies.html) and then import your repository twice under Read the Docs --one time per set of documentation you want to host: mydocs-users and mydocs-developers, for example.
Note that this is the exact pattern that Read the Docs itself uses for its documentation:
User's documentation: https://docs.readthedocs.io/
Developer's documentation: https://dev.readthedocs.io/
The repository for both sets of documentation is the same (https://github.com/readthedocs/readthedocs.org/) but documentation generated on each of the projects is defined by that sphinx-multiproject extension. See https://github.com/readthedocs/readthedocs.org/blob/6bf0bede7b757f1e9458e29ba89b591389cae4d5/docs/conf.py#L48-L63
Be sure you follow the tutorial.
Usually you need an index (in conf.py it is referred as master_doc).
Then each file must be referenced, either in a toctree or a include, or a link, etc.
Look at examples on github (ie: the Sphinx-doc repository).
I have a website that has related pages. They have links that point back and forth to one another but I have no integrated system, nor do I know what that would mean.
What is the minimum code that a group of web pages must have to be considered a Content Management System (CMS). Is it that all the settings are in the database and the pages are generated somehow? Is there some small snippet that all my pages could share that makes them a CMS, database or not?
Thanks. I was also hoping not to have to study a giant CMS to see what makes it a CMS . After maybe a basic understanding I would know what I was looking for.
edit: here's why I ask about code. Whenever I have looked at a CMS, and maybe they aren't all the same, I saw that to develop a module you always had to inherit from certain classes and had some necessary code. I didn't know if there was some magic model that I just don't get that all cms makers understand.
edit: perhaps my question is more about being extendable or pluggable. What would a minimum look like? Is it possible to show that here?
edit: how about this? Is something a CMS if it is not extendable and/or pluggable?
I think this is really impossible to say. We all manage content. The "system" is just whatever mechanism you use to do so(dragging and dropping in Explorer or committing content changes via a SQL query). To say there is a minimum amount of code needed really isn't indicative. What is indicative is how often you find yourself making mistakes and how easy it is for a given user of a given skill level and knowledge to execute the functions in the designed system. That tells you the quality/degree of what you have in place being worthy of being called a "CMS."
Simply put a CMS is an application that allows the user to publish and edit existing web content.
In response to the edit:
A "good" CMS allows of extensibility. By using inheritence you can extend the functionality of a CMS outside of the core components provided. That's the magic.
About Extensibility:
Depending on the language/framework you want to build your CMS with, you can load pages or controls(ASP.NET) using command built into the framework. Typically what is being done is a parent class/interface is being defined that forces an module that is to be developed to follow some given standards:
Public MustInherit Class CMSModule
'Here you will define properties and functions that need to be global to all modules being developed to extend your CMS.
public property ModuleName as string
End Class
public class PlugInFooCMSPage
inherits CMSModule
end class
Then it's just a matter of simply loading a module dynamically in whatever construct a given language/framework provides.
Ultimately, a CMS is a system that lets you manage content, so it needs an user interface that is dedicated to letting you easily create, edit and delete pages on your website.
However, it's fairly usual to expect from a CMS to provide a browser-based WYSIWYG page editor, file uploading, image resizing, url rewriting, page categories and tags, user accounts (editor, moderator, administrator), and some kind of templae system.
Without dragging you into a theoretical explanation of what a CMS is and what it's not, perhaps some tutorials on the building methodology of a CMS will help you better understand.
http://css-tricks.com/php-for-beginners-building-your-first-simple-cms/
http://www.intranetjournal.com/php-cms/
A Content Management System is a System that Manages Content. :)
So if you got many pages that share the same layout, you can create a system that stores the content into a database and when a page is requested, it gets that content, merges it with a template that contains the page header, menu, etc.. and outputs the result.
The basis idea is that you don't want to copy HTML pages, and have to edit hundreds of them when you want to change your layout.
Such a system can be very complex, featuring wysiwyg editors, toolbars, version control, multiple user publishing and much more, but it could be as simple as a single page behind a standard loging, that contains only an input field for the title and a textarea in which you type the html content.
I have several copies of the same PDF file. These copies have annotations in it (Rect type with pop-up comments).
I want to know if I can get all these annotations from these copies and aggregate them into a single master copy using CAM::PDF (or another free tool).
an example to illustrate:
I have file1_userA.pdf and file1_userB.pdf. They are both annotated.
I want to generate file1_allusers.pdf aggregating annotations from both files file1_userA.pdf and file1_userB.pdf.
ps: I have the original un-annotated copy.
-- EDIT (Aug, 4):
I have developed an extension for CAM::PDF, namely CAM::PDF::Annot. It 'use base's CAM::PDF and adds extra functionality regarding Drawing Markup Annotations.
I am in the process of tidying up the code so I can post it to CPAN.
-- EDIT (Aug, 19)
I have finally submitted it to PAUSE, but I am running into some world writable related problems...
In any case, if anyone is interested in taking a look at the code, I will try and make it available somewhere... until then, just PM me and I will mail it to you.
geez, i'm getting such a thrill posting a module to cpan... i found the joy of working in working with Perl...
best regards,
Donato Azevedo
I'm the author of CAM::PDF. I have built only very limited support for annotations to date, specifically just for form field filling. So, no, that's not a supported feature today. The feature you describe is very interesting, though, and I can imagine that others would use it too, so I'd be interested in discussing it further with you offline.