Forking and publishing

The steps below are a walk-through to contribute to this repository, It ensures that GitHub Actions and GitHub Pages are enabled, so you can run continuous integration and see the pages live at <your_user>.github.io/documentation, and git-lfs artifacts are properly synced.

Note

Using the Python virtual environment (venv) is recommended, but if you wish to not use it, skip steps in green.

Preparing your origin

There is three options to host your work, for users:

  • Fork: that want to use the GitHub flow (recommended).

  • Copy: that want to work privately first.

  • Branch: with write access to analogdevicesinc organization.

Fork

Ensure git-lfs is installed with:

sudo apt install git-lfs -y

Fork the analogdevicesinc/documentation repo on your account.

Enable the workflows on the forked repo at github.com/<your_user>/documentation/actions by clicking the green button
“I understand my workflows, go ahead and enable them”.

Clone the repository:

~$

git clone https://github.com/<your_user>/documentation \
    --depth=10 -- documentation

~$

cd documentation

Copy

Ensure git-lfs is installed with:

sudo apt install git-lfs -y

Clone mainland:

~$

git clone https://github.com/analogdevicesinc/documentation \
    --depth=10 -- documentation

~$

cd documentation

Setup both origins, for example, call analogdevicesinc public and your copy private at the .git/config, similar to:

[core]
     repositoryformatversion = 0
     filemode = true
     bare = false
     logallrefupdates = true
[remote "public"]
     url = https://github.com/analogdevicesinc/documentation.git
     fetch = +refs/heads/*:refs/remotes/public/*
[remote "private"]
     url = https://github.com/<your_user>/documentation.git
     fetch = +refs/heads/*:refs/remotes/private/*
[branch "main"]
     # Set your private copy as upstream
     remote = private
     merge = refs/heads/main

Push the working branch to your copy.

~/documentation$

git push private main:main

Fetch from analogdevicesinc and push to your copy the large files binaries:

~/documentation$

git lfs fetch --all public

~/documentation$

git lfs push --all private

Branch

If you have write permission to the repository, you shall add your work to a branch at mainland, then just:

Ensure git-lfs is installed with:

sudo apt install git-lfs -y

Clone the repository

~$

git clone https://github.com/analogdevicesinc/documentation \
    --depth=10 \
    -- documentation

~$

cd documentation

Create and checkout a branch

~/documentation$

git checkout -b <your_branch>

Preparing your environment

Clone and build the doc for the first time (working directory: repo root):

Ensure pip is up-to-date:

pip install pip --upgrade

Setup the virtual env at the repo root path:

~/documentation$

python -m venv ./venv

Activate the virtual env:

~/documentation$

source ./venv/scripts/activate

Install the requirements:

~/documentation$

(cd docs ; pip install -r requirements.txt --upgrade)

Build the doc (output at docs/_build/html):

~/documentation$

(cd docs ; make html)

Adding content

Add a new topic and pages (working directory: docs).

On index.rst, add a new topic:

.. toctree::
   :caption: My new topic
   :maxdepth: 2

    my_topic/index

Or add to an existing, for example, in eval/index.rst.

Tip

Don’t overthink the location at this point, it can be easily moved later.

Create a new folder and file matching the entry from last step:

~/documentation/docs$

mkdir my_topic; touch my_topic/index.rst

Edit my_topic/index.rst, adding a title and some content.

Build the doc and see the changes.

Commit the changes.

For a extensive guide on adding content see Creating new pages.

Pushing and triggering the CI

The CI (.github/workflows/top-level.yml) builds the doc and pushes to the gihub-pages branch and is triggered on push to main and on pull request (every time):

  • On pull request, the build doc target is run, which builds the doc and stores it as an artifact.

  • On push to main, the build doc and deploy targets are run, the latter commits the doc artifact to the gh-pages branch.

Tip

You can see the runs at github.com/<your_user>/documentation/actions.

Enable GitHub Pages to have the public website configure GitHub Pages at github.com/<your_user>/documentation/settings/pages:

  • Set Source as “deploy from branch”

  • Set the branch as “gh-pages”

Resuming work at a later time

Reactivate the virtual environment with:

~/documentation$

source ./venv/scripts/activate

Ensure the tools are up to data from time to time with:

~/documentation$

(cd docs ; pip install -r requirements.txt --upgrade)

Edit, build, commit, push as usual.

Understanding git lfs

Since git lfs is not that common in the wild, it may be tricky to get the hang of it.

First of all, the basics: lfs replaces binaries files with pointers, and stores the binaries outside the git repository, in an external server.

When you do git clone/pull, by default lfs will also download the binaries at the “smudge” step. You can change this behaviour by setting globally git lfs install --skip-smudge or temporally with GIT_LFS_SKIP_SMUDGE=1 environment variable.

If during a clone or pull you obtain the error:

Encountered n file(s) that should have been pointers

That simply means that someone pushed files to remote that should have been pointers (defined in the .gitattributes file). And to fix is simple:

~$

git add --renomalize .

~$

git commit -m "Convert binary files to pointers"

~$

git push

And advise the committer to ensure he has git lfs enabled with git lfs install.