PoDoFo documentation ?

Question

PoDoFo documentation ?

seba1204 opened this issue a year ago · comments

TL;DR
I don't find any documentation for this lib.

Hello, thanks for this amazing lib ! I'd like to use it, but I don't know how. I'm probably blind, but I couldn't find any documentation.
Maybe a simple link to the README.md file could be added, even from an old version?

I've found some links:

But none of them seems to be a real detailed documentation.
I seem to remember a few months ago coming across more details, but I can't find anything.

Could you help me?
Thanks!

Nadwey · Answer 1 · Mon Oct 02 2023 14:02:48 GMT+0800 (China Standard Time)

I also couldn't find any docs, so I setup a repo that generates them every week

https://nadwey.github.io/podofo-docs/

Francesco Pretto · Answer 2 · Tue Oct 31 2023 01:32:24 GMT+0800 (China Standard Time)

I'm sorry, but I'm not the right person to write beginners focused documentation: 100% of the effort is now put on creating a very powerful API that is high level enough that people won't need to bother too much with PDF internals, but it's a very big task and I can't guarantee I am succeeding in every aspect of this big work. I made all I could to keep updated the Doxygen documentation, but for sure I'm forgetting a lot methods, especially the many overloads added for which I would like to not clutter the headers too much. To me, Doxygen documentation duplication smells as bad as code duplication because it also gets outdated very quickly: suggestions welcome on how to handle this.

I never generated the documentation myself so I would be glad to integrate a github workflow that:

Generate the documentation
Upload it to a github repository. In the end I will push it to github pages repository so I can put a link to it.

Patch welcome.

francesco scalise · Answer 3 · Tue Oct 31 2023 17:24:17 GMT+0800 (China Standard Time)

Hello,

I've made an initial attempt to address this issue. In this branch: feature/issue-91, I've tried to create automated documentation using Doxygen. You can download and see the results here.

Before you delve into it, here are some considerations regarding this attempt:

Platform Testing: The entire testing was done on macOS.
Workflow Limitations: The documentation workflow is currently missing for Linux and Windows.
Nature of Work: Please note that this is merely a Proof of Concept (POC), and the idea is to extract specific tasks from this for more comprehensive work.

I hope this helps, and I'm keen on receiving any feedback or suggestions you might have on the documentation. Thank you!

Francesco Pretto · Answer 4 · Tue Oct 31 2023 18:02:23 GMT+0800 (China Standard Time)

Hello @ferencIOS. Thank you for your efforts. Some comments:

Workflow Limitations

I believe there's no need to have workflow steps in each platform. One separate workflow doing just documentation would be good enough, which should be possible I believe. So I recommend to strip the documentation part from the mac workflow and leave that unmodified.

Platform Testing

I would prefer the workflow to run on linux, since it's just faster on github (mac workflows are very slow). That's something I can port later, just in case.

I also would like to see the github git repository push step in action.

francesco scalise · Answer 5 · Fri Nov 03 2023 17:13:50 GMT+0800 (China Standard Time)

Hello @ceztko

Thank you for your feedback. Following your suggestions, I have refined the workflow to align with the project's requirements:

Workflow Streamlining: The documentation steps have been isolated from the macOS workflow. There is now a separate workflow solely dedicated to documentation generation.
Platform Choice: Although the initial tests were conducted on macOS, I concur with your preference for Linux due to its quicker execution on GitHub. The current workflow now utilizes ubuntu-latest for documentation generation.
Documentation Deployment: I've successfully implemented the GitHub repository push step, and the automated documentation is now live. You can view the deployed documentation at https://ferencios.github.io/podofo/.

The associated branch and the workflow file can be reviewed here:
master...ferencIOS:podofo:feature/issue-91

Please note the following workflow details:

name: build-documentation

on:
  push:
    branches: [appropriate-branch]
  pull_request:
    branches: [appropriate-branch]
  
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

env:
  BUILD_TYPE: Release

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      # Other steps truncated for brevity...
  deploy:
    needs: build-and-deploy
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

In alignment with the environment protection rules, I am ready to transition the workflow to the appropriate branch that is permitted to deploy to github-pages.

To ensure the workflow functions correctly and complies with the repository's environment protection rules, the following steps have been taken:

Navigate to the GitHub repository settings.
Access the "Environments" section.
Select the github-pages environment to review the protection rules that are in place.

Francesco Pretto · Answer 6 · Tue Dec 05 2023 06:43:54 GMT+0800 (China Standard Time)

@ferencIOS Please, can you squash and create a PR? I will handle merging with my customization later.

Francesco Pretto · Answer 7 · Tue Dec 05 2023 08:23:20 GMT+0800 (China Standard Time)

To ensure the workflow functions correctly and complies with the repository's environment protection rules, the following steps have been taken:

Navigate to the GitHub repository settings.

Access the "Environments" section.

Select the github-pages environment to review the protection rules that are in place.

These steps are not clear to me. I can create a github-pages environment, but then what I should do?

Also I'm not entirely sure to which repository the pages will be uploaded to and at which location. Maybe it's set automatically to push the default <repository>.github.io repo, but I'm not entirely sure. Also I would like the location to be https://podofo.github.io/documentation and not https://podofo.github.io/podofo, as it appears to be in your environment.

Francesco Pretto · Answer 8 · Wed Dec 20 2023 04:51:58 GMT+0800 (China Standard Time)

Hi @ferencIOS . Again, if you can create a PR (as is, or rebased and squashed), otherwise it's a non start.

francesco scalise · Answer 9 · Wed Dec 20 2023 05:28:18 GMT+0800 (China Standard Time)

Hi @ceztko!

The PR can be found here: #120.

Now, it is necessary for you to perform a few steps in your GitHub repository settings.
Here's a brief guide:

Navigate to the 'Settings' of your GitHub repository.
Access the 'Environments' section within the settings.
Select the 'github-pages' environment.
Review and adjust the protection rules as needed to accommodate the new documentation.

Let me know if I can help you.

Francesco Pretto · Answer 10 · Wed Dec 20 2023 05:38:37 GMT+0800 (China Standard Time)

Hi @ferencIOS . These steps are not clear at all for me:

Select the 'github-pages' environment.

Review and adjust the protection rules as needed to accommodate the new documentation.

Let me show what I have in my panels. If I go to Ennviroments, there was no pre-created github-pages environment, I had to create it myself with the "New environment" button.

Then if I enter such created environment that's what I see:

In other words there's nothing obvious to do as when you say "Review and adjust the protection rules as needed to accommodate the new documentation.". Please assume I know nothing about "protection rules". You will have to go in a more detailed explanation, or show me a screenshot of your settings.

Francesco Pretto · Answer 11 · Wed Dec 20 2023 05:47:28 GMT+0800 (China Standard Time)

Ok, I did some progress. You should really have specified that I must go to the podofo.github.io settings, and not the podofo main repository. Here I actually found a github-pages environment already created. In the configuration panel that's what I see (below). Again, for me it's not really clear what to do here. Assume you have to tell your mother :) ...

francesco scalise · Answer 12 · Wed Dec 20 2023 06:16:50 GMT+0800 (China Standard Time)

Let me show what I have in my panels. If I go to Ennviroments, there was no pre-created github-pages environment, I had to create it myself with the "New environment" button.

Yes, you have to do it.

Please switch to the most appropriate branch: main is ok

update the YAML configuration for triggering actions on chosen branch

.github/workflows/build-documentation.yml

push:
  branches: [chosen-branch-name]
pull_request:
  branches: [chosen-branch-name]

Francesco Pretto · Answer 13 · Thu Dec 21 2023 07:00:26 GMT+0800 (China Standard Time)

One step that was necessary to have the doxygen workflow was enabling deploy through Github actions.in the Pages tab of the podofo repository (screenshot below), otherwise I had an error. After that I found github-pages automatically created in the Environments of podofo repository. No need to perform any change in it, though. Actually the pages are not committed to the podofo.github.io repository as I expected, but they are still visible in a "virtual" http location called podofo within the project pages entry point https://podofo.github.io. I changed the html output directory to be called documentation instead so, the final link for the documentation is https://podofo.github.io/podofo/documentation/ . More changes are planned, as create a target for doxygen generation within CMake, but for now this is done. Thank you @ferencIOS

Francesco Pretto · Answer 14 · Thu Dec 21 2023 08:23:14 GMT+0800 (China Standard Time)

I updated my last comment with more discoveries: eventually the github-pages was created automatically by enabling Pages deploy through actions. No need to perform any changes in it, though.